Geometry API

https://api.geocode.earth/v1/geometry

The Geometry API returns polygon geometries in GeoJSON format for specific records, using a Global ID (GID) returned from another endpoint.

You can use this endpoint to fetch detailed boundary information for administrative areas. This allows you to, for example, display boundaries on a map or perform spatial analysis.

Basic usage #

The geometry endpoint requires the gid parameter and accepts an optional detail parameter to control the level of detail in the returned geometry.

Parameters:

• api_key: Your Geocode Earth API key
• gid: A Global ID like whosonfirst:locality:101909779
• detail: high, medium, or low (optional, defaults to medium)

curl --get https://api.geocode.earth/v1/geometry \
  -d api_key=<YOUR API KEY> \
  -d gid=whosonfirst:locality:101909779 \
  -d detail=medium | jq -r '.features[0] | .geometry.type, .properties.gid'

require 'net/http'
require 'json'

api_key = '<YOUR API KEY>'
query = "https://api.geocode.earth/v1/geometry?"\
        "api_key=#{api_key}&"\
        "gid=whosonfirst:locality:101909779&"\
        "detail=medium"
http_response = Net::HTTP.get_response(URI(query))
response = JSON.parse(http_response.body)

puts response['features'][0]['geometry']['type']          # Polygon or MultiPolygon
puts response['features'][0]['properties']['gid']         # whosonfirst:locality:101909779

const api_key = '<YOUR API KEY>';
const url = new URL('https://api.geocode.earth/v1/geometry');
url.searchParams.set('api_key', api_key);
url.searchParams.set('gid', 'whosonfirst:locality:101909779');
url.searchParams.set('detail', 'medium');

(async () => {
  const response = await fetch(url);
  const data = await response.json();
  console.log(data.features[0].geometry.type);             // Polygon or MultiPolygon
  console.log(data.features[0].properties.gid);            // whosonfirst:locality:101909779
})();

import json
import urllib.request

api_key = '<YOUR API KEY>'
query = "https://api.geocode.earth/v1/geometry?" \
        "api_key="+api_key+"&"\
        "gid=whosonfirst:locality:101909779&"\
        "detail=medium"

response = json.load(urllib.request.urlopen(query))

print(response['features'][0]['geometry']['type'])          # Polygon or MultiPolygon
print(response['features'][0]['properties']['gid'])         # whosonfirst:locality:101909779

{
  "type": "FeatureCollection",
  "features": [{
    "type": "Feature",
    "geometry": {
      "type": "Polygon",
      "coordinates": [
        [
          [13.500218, 52.613791],
          [13.498546, 52.610683],
          [13.496752, 52.605094],
          [13.499004, 52.605164]
        ]
      ]
    },
    "properties": {
      "gid": "whosonfirst:locality:101909779",
      "source": "whosonfirst",
      "layer": "locality",
      "id": "101909779",
      "source_id": "101909779"
    },
    "bbox": [13.088333, 52.338242, 13.760469, 52.674917]
  }]
}

GIDs with geometries #

Not all records from our service have polygon geometries—many are just points. Only records with a polygon (or multi-polygon!) geometry will be returned from the geometry endpoint.

Records from the whosonfirst source will likely have a geometry. If you query the geometry endpoint for a record with no geometry, you’ll receive an HTTP 404 response. These don’t count towards any of your request quotas.

Detail level comparison #

Explore different detail levels with Berlin (wof:locality:101909779) or enter your own GID using the controls on the map. Zoom in and out to see how each detail level performs at different scales.

Detail levels #

Geometry information can be quite large, so we offer 3 detail levels: high, medium, and low. High has the most detail, but also the largest number of points and thus requires the largest data transfer.

High detail #

High detail is best when you are displaying a single record, especially at high zoom levels (i.e., only a small part of the globe is displayed at once). If you want to show the boundary between two cities, or even countries at the level of individual roads and houses, for example, high detail is a good choice.

Some geometries that cover large areas, like countries, will be several megabytes in size, though most are smaller.

Medium detail #

Medium detail is designed to reduce the geometry size as much as possible while still being indistinguishable from the original geometry when the entire geometry is in view.

For example, you won’t notice any difference viewing the medium detail geometry for all of Russia, even though it’s an order of magnitude smaller in size. However, you will definitely notice the difference if you are zoomed in on the border of Russia and China.

Medium is a good default for display if you have a few geometries at once.

Low detail #

Low detail is designed to keep all geometries at a minimum file size while still preserving their general shape. If you’re concerned about bandwidth, like over a mobile network connection, or the CPU cost of displaying many geometries, low should still work well.

If you’re displaying, for example, most of the 3200 counties in the United States, low detail is a good choice. But you likely don’t want low detail if you’re zoomed into a single county.