USGS_NAMES Function

Reference Guide > U–V Routines > USGS_NAMES Function

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}