USGS_NAMES Function
Queries a database containing names, FIPS codes, and longitude/latitude values for cities and towns in the United States.
Usage
result = USGS_NAMES( [name] )
Input Parameters
name—(optional) A string parameter containing the name of a city or town. All names that begin with this string are returned. If you omit the name parameter, then the entire database if returned.
Keywords
County—Specifies either a string containing the county name or the county FIPS code. By default, no county is specified.
State—Specifies either a string containing the two-letter state abbreviation or an integer specifying the state FIPS code. By default, no state is specified.
Returned Value
result—An unnamed structure array containing the city or town name, state FIPS code, county FIPS code, longitude, and latitude.
Discussion
The search string arguments are not case sensitive. A search for city names
BOULDER and boulder produce identical results.
The result of this function is an unnamed structure array. If state and county are specified as strings, then the result is given in the form:
{, name:'', state:0, county:0, lon:0.0, lat:0.0}where the state and county tags’ fields are FIPS numbers (integers).
If State and County are specified as FIPS numbers (integers), the result is given in the form:
{, name:'', state:'', county:'', lon:0.0, lat:0.0} where the state tag field is a string containing the two-letter state abbreviation and the county tag field is a string containing the name of the county.
The county tag field will only be included in the output if the County keyword is specified.
If no matches are found, a structure is returned with all fields set to zero or an empty string, as appropriate.
Example 1
Find the longitude and latitude of Boulder, Colorado:
boulder = USGS_NAMES('boulder', State='CO')PRINT, boulder.lon, boulder.lat
; PV-WAVE prints: -105.270 40.0150
Example 2
Find the FIPS codes for Colorado and Larimer county:
codes = USGS_NAMES(State='CO', County='Larimer')
PRINT, codes(0).state, codes(0).county
; PV-WAVE prints: 8 69
Example 3
Find the two-letter state abbreviation and the county name given the FIPS codes:
result = USGS_NAMES(State=8, County=69)
PRINT, result(0).state, ', ', result(0).county
; PV-WAVE prints: CO, Larimer
Example 4
Return all the towns in the database named “Lincoln”:
result = USGS_NAMES('Lincoln')FOR i=0L,N_ELEMENTS(result)-1 DO PRINT, result(i)
; PV-WAVE prints: { Lincoln 5 143 -94.4233 35.9494}; This is a one-line sample of the output. The complete output
; is not shown for this example.
Example 5
Return all the towns in Larimer county, Colorado:
; This is a three-line sample of the output. The complete output
; is not shown for this example.
result = USGS_NAMES(State='CO', County='Larimer')
FOR i=0L,N_ELEMENTS(result)-1 DO PRINT, result(i)
; PV-WAVE prints the following (only the first 3 lines shown):
; { Berthoud 8 69 -105.081 40.3083}; { Buckeye 8 69 -105.094 40.8272}; { Drake 8 69 -105.340 40.4319}See Also
