Geoserve Places Endpoint

The places endpoint allows users to search for places within a certain distance of a geographical point (circle search), or users can search for places within a latitude/longitudinal range (rectangle/box search).

Data returned by the Geoserve Web Service places endpoint is provided by the Geonames geographical database.

Request

Syntax

A geoserve places search takes the following form:

  https://staging-earthquake.usgs.gov/ws/geoserve/places.json?{parameters}

Parameters

Circle Search Parameters

• latitude Number
  Latitude in decimal degrees of center point. [-90, 90].
• longitude Number
  Longitude in decimal degrees of center point. [-180, 180].
• maxradiuskm Number
  Search radius (in kilometers) from the center point. [0, 6371].

Rectangle Search Parameters

• maxlatitude Number
  Upper latitude bound in decimal degrees. [-90, 90].
• minlatitude Number
  Lower latitude bound in decimal degrees. [-90, 90].
• maxlongitude Number
  Upper longitude bound in decimal degrees. [-180, 180].
• minlongitude Number
  Lower longitude bound in decimal degrees. [-180, 180].

Optional Search Parameters

• limit Number
  Limit number of results, sorted by distance. The event result type will always include 5 places regardless of the requested limit. [0, +Inf].
• minpopulation Number
  Limit results to places where population is greater than or equal to minpopulation. [0, +Inf].
• type Enumeration
  The type of search being performed. Comma-separated list.

  geonames

  Data were created by Geonames and can be found here.

  event

  This dataset makes use of the geonames underlying data with custom logic to determine relevant populated places near a seismic event.

• featurecode String
  Geonames feature code. For example PPLA.
  See Geonames feature codes for a list of all feature codes.
  Note that only code starting with P are available.

Notes

Response

The response is formatted as one or more nested GeoJSON FeatureCollections. Each nested GeoJSON FeatureCollections is keyed by the request type.

Properties

Each returned Feature in the GeoJSON FeatureCollection includes an id, a geometry object with longitude, latitude, and elevation, and a properties object with the following attributes:

Geonames/Event

• admin1_code String
  Three character code for primary administrative division of a country, such as a state in the United States.
• admin1_name String
  Name of a primary administrative division of a country, such as a state in the United States.
• azimuth Number
  Direction (in decimal degrees [0, 360]) from the Feature to the center point (latitude, longitude).
• country_code String
  ISO-3166 2-character country code.
• country_name String
  Name of country.
• distance Number
  Distance (in kilometers) from the Feature to the center point (latitude, longitude).
• feature_class String
  Geonames feature class used to describe the Feature.
• feature_code String
  Geonames feature code used to describe the Feature.
• id Number
  ID in geonames database.
• name String
  Name of the Feature.
• population Number
  Population associated with the Feature.

Examples

Below are example requests and responses that detail the nested GeoJSON structure. Each type has a nested GeoJSON FeatureCollection that may contain multiple GeoJSON features. Click the link for an example to see the response.

• Five nearest places within 100km of a point:

  https://staging-earthquake.usgs.gov/ws/geoserve/places.json?latitude=39.75&longitude=-105.2&maxradiuskm=100&limit=5&type=geonames

• All places within 100km of a point with at least 1,000 people:

  https://staging-earthquake.usgs.gov/ws/geoserve/places.json?latitude=39.75&longitude=-105.2&maxradiuskm=100&minpopulation=1000&type=geonames

• All places within a rectangle with at least 10,000 people:

  https://staging-earthquake.usgs.gov/ws/geoserve/places.json?minlatitude=39&maxlatitude=40&minlongitude=-105&maxlongitude=106&minpopulation=10000&type=geonames

• An event type request that always returns 5 places near a point:

  https://staging-earthquake.usgs.gov/ws/geoserve/places.json?latitude=45.1&longitude=-70.1&type=event