Release Date:
The U.S. Geological Survey Search API is a custom JavaScript library useful for creating a location search widget in a webpage, typically in conjunction with a web map. The widget connects to a database created for the API, or Application-Programming Interface, to quickly find and suggest locations as the user enters text to navigate to areas of interest.
The purpose of this API is to provide a search tool for locations contained in the Geographic Names Information System database, the official United States government registry of places names.
“The GNIS contains abundant information about the official names for places, features and areas in the 50 states, District of Columbia and territories and outlying areas of the U.S., such as Puerto Rico, Guam and the U.S. Virgin Islands,” said Lou Yost, executive secretary for the U.S. Board on Geographic Names. “It is exciting to see the new USGS Search API leverage these data and provide new opportunities for the public to access GNIS and expand its use into a wide array of web products.”
The Search API is also suitable for hydrologic applications, excludes commercial locations, is customizable and is intuitive to use. Additional features include:
- Framework Independence: The widget can be used in conjunction with Leaflet, ESRI JSAPI or other web-mapping frameworks.
- Database Richness: Beyond cities and towns, GNIS is the authoritative place name registry for the nation that also includes streams, lakes, dams, basins, parks, bridges, hospitals, schools and much more.
- Suggestion Organization: Suggestions are grouped by category, making it easier to find what you are looking for.
- Automatic State Filtering: An entry ending in a two-character U.S. state abbreviation automatically restricts suggestions to that state.
- Wild Card Support: Wild card matching is performed on entries containing one or more asterisks.
- Latitude-Longitude Recognition: Entries such as “40.1 -90.2” are automatically identified as geographic coordinates in decimal form.
- Customizable Behavior: Many options are available for configuring the widget, such as the search area and types of suggestions to include.
- Customizable Appearance: A structured CSS class system allows flexible customization of widget appearance.
This image demonstrates how the USGS Search API can be used to show the suggested locations appearing in the menu on the map. The map function will update as text is typed in the Search API widget text box.
The API database contains about 3.7 million location records from a variety of sources, including:
- GNIS Places: Approximately 2.1 million places registered with the Geographic Names Information System.
- USGS Monitoring Stations: Over 1.4 million USGS surface water, groundwater, spring, atmospheric and other sites in the USGS National Water Information System.
- Hydrologic Units: Over 120,000 two-, four-, six-, eight-, 10- and 12-digit hydrologic unit codes.
- Zip Codes: Over 30,000 5-digit postal (zip) codes compiled from the ESRI USA ZIP Code Areas dataset.
- Area Codes: About 290 three-digit telephone area codes for the nation.
- U.S. States: The 50 U.S. states plus the District of Columbia, the U.S. Virgin Islands and Puerto Rico.
The widget can be configured to include or exclude each of these sources as required for a user’s particular application. When no location match is found in the API database, the ESRI ArcGIS Online Geocoding Service can be used as a secondary data source.
For access to the latest version of the USGS Search API, documentation and source code developed and maintained by the USGS Texas Water Science Center, visit the API homepage. Developers may also contribute using a version of the source code hosted at the collaborative USGS GitHub community.
