Customizing Forward Geocoding

Queries to the Search, Autocomplete, and Structured Search endpoints can be customized using query parameters.

The parameters supported by Geocode Earth endpoints enable:

Using a coordinate to prefer nearby results
Restricting results to those in a bounding box
Restricting results to those within a circle
Restricting results to one or more countries
Restrict results by parent ID
Filtering results by layer
Changing the number of results returned

Use a coordinate to prefer nearby results #

Prefer results near a coordinate with focus.point

Use the focus.point parameter to prefer results near a particular coordinate. Results far away from the focus point may still be returned, but only if they are important (such as a major city or landmark).

A focus point can be used in many ways. Some examples:

Use the center of the currently visible section of a web map to prefer visible results
Use a devices current location returned via GPS to prefer results that are nearby
Use the center of a large metropolitan area to prefer results in that area

For example, using focus.point, its possible to easily return Starbucks coffee shops near midtown Manhattan:

We've securely inserted your Geocode Earth API key in the example code below.

Shell Ruby Node.js Python

curl --get https://api.geocode.earth/v1/autocomplete \
  -d api_key=<YOUR API KEY> \
  -d focus.point.lat=40.7566 \
  -d focus.point.lon=-73.9859 \
  -d text=starbucks

require 'net/http'
require 'json'

api_key = '<YOUR API KEY>'
query = "https://api.geocode.earth/v1/autocomplete?"\
        "api_key=#{api_key}&"\
        "focus.point.lat=40.7566&" \
        "focus.point.lon=-73.9859&" \
        "text=starbucks"
http_response = Net::HTTP.get_response(URI(query))
response = JSON.parse(http_response.body)

puts response # print the entire response

puts response['features'][0]['properties']['name']      # Starbucks
puts response['features'][0]['properties']['label']     # Starbucks, Manhattan, New York, NY, USA
puts response['features'][0]['geometry']['coordinates'] # [ -73.978206, 40.756391 ]

const api_key = '<YOUR API KEY>';
const url = new URL('https://api.geocode.earth/v1/autocomplete');
url.searchParams.set('api_key', api_key);
url.searchParams.set('focus.point.lat', '40.7566');
url.searchParams.set('focus.point.lon', '-73.9859');
url.searchParams.set('text', 'starbucks');

(async () => {
  const response = await fetch(url);
  const data = await response.json();
  console.log(data); // print the entire response

  console.log(data.features[0].properties.name);      // Starbucks
  console.log(data.features[0].properties.label);     // Starbucks, New York, NY, USA
  console.log(data.features[0].geometry.coordinates); // [ -73.978206, 40.756391 ]
})();

import json
import urllib.request

api_key = '<YOUR API KEY>'
query = "https://api.geocode.earth/v1/autocomplete?" \
        "api_key="+api_key+"&"\
        "focus.point.lat=40.7566&" \
        "focus.point.lon=-73.9859&" \
        "text=starbucks"

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

print(response) # print the entire response

print(response['features'][0]['properties']['name'])      # Starbucks
print(response['features'][0]['properties']['label'])     # Starbucks, Manhattan, New York, NY, USA
print(response['features'][0]['geometry']['coordinates']) # [ -73.978206, 40.756391 ]

This will return several Starbucks shops, all near the specified focus point. Each returned result will include the distance from the point in the distance property:

Response

{
  "features": [{
    "type": "Feature",
    "geometry": {
      "type": "Point",
      "coordinates": [
        -73.983769,
        40.75491
      ]
    },
    "properties": {
      "id": "node/2611782759",
      "gid": "openstreetmap:venue:node/2611782759",
      "layer": "venue",
      "source": "openstreetmap",
      "source_id": "node/2611782759",
      "name": "Starbucks",
      "housenumber": "1100",
      "street": "6th Avenue",
      "postalcode": "10036",
      "distance": 0.26,
      "accuracy": "point",
      "country": "United States",
      "country_gid": "whosonfirst:country:85633793",
      "country_a": "USA",
      "region": "New York",
      "region_gid": "whosonfirst:region:85688543",
      "region_a": "NY",
      "county": "New York County",
      "county_gid": "whosonfirst:county:102081863",
      "county_a": "NE",
      "locality": "New York",
      "locality_gid": "whosonfirst:locality:85977539",
      "locality_a": "NYC",
      "borough": "Manhattan",
      "borough_gid": "whosonfirst:borough:421205771",
      "neighbourhood": "Midtown West",
      "neighbourhood_gid": "whosonfirst:neighbourhood:85882233",
      "continent": "North America",
      "continent_gid": "whosonfirst:continent:102191575",
      "label": "Starbucks, Manhattan, New York, NY, USA"
    }
  }]
}

Restrict results to a bounding box #

Try in Explorer

Filter results by a bounding box

Use a bounding box filter to return results only in a specified rectangular area. Bounding box filters require four parameters: boundary.rect.min_lat, boundary.rect.min_lon, boundary.rect.max_lat, and boundary.rect.max_lon.

Restrict results to a circle #

Try in Explorer

Filter results by a circle

Use a circle filter to return results only within a given distance of a coordinate. Circle filters require both the boundary.circle.lat and boundary.circle.lon parameters, which set the center of the circle.

The optional boundary.circle.radius parameter sets the radius of the circle, in kilometers. If it is not set, a radius of 50km is used.

For example, to find YMCA locations within 35km of a point near Toronto, use boundary.circle.lat=43.818156, boundary.circle.lon=-79.186484 and boundary.circle.radius=35.

Unlike focus.point, which only prefers nearby results, a circle filter excludes everything outside the circle. To return nearby results sorted by distance, use both together, with the same coordinate for focus.point and boundary.circle.

Restrict results to one or more countries #

Try in Explorer

Use a country filter to return results only in specified country. Country filters use the boundary.country parameter and require a comma-delimited list of ISO 3166-1 country codes (2 or 3 letter variants).

For example, to restrict results to France and Germany, use boundary.country=FRA,DE.

We've securely inserted your Geocode Earth API key in the example code below.

Shell Ruby Node.js Python

curl --get https://api.geocode.earth/v1/autocomplete \
  -d api_key=<YOUR API KEY> \
  -d boundary.country=FRA,DE \
  -d text=laduree

require 'net/http'
require 'json'

api_key = '<YOUR API KEY>'
query = "https://api.geocode.earth/v1/autocomplete?"\
        "api_key=#{api_key}&"\
        "boundary.country=FRA,DE&" \
        "text=laduree"

http_response = Net::HTTP.get_response(URI(query))
response = JSON.parse(http_response.body)

puts response # print the entire response

puts response['features'][0]['properties']['name']      # Ladurée
puts response['features'][0]['properties']['label']     # Ladurée, Paris, France
puts response['features'][0]['geometry']['coordinates'] # [ 2.321311, 48.869867 ]

const api_key = '<YOUR API KEY>';
const url = new URL('https://api.geocode.earth/v1/autocomplete');
url.searchParams.set('api_key', api_key);
url.searchParams.set('boundary.country', 'FRA,DE');
url.searchParams.set('text', 'laduree');

(async () => {
  const response = await fetch(url);
  const data = await response.json();
  console.log(data); // print the entire response

  console.log(data.features[0].properties.name);      // Ladurée
  console.log(data.features[0].properties.label);     // Ladurée, Paris, France
  console.log(data.features[0].geometry.coordinates); // [ 2.321311, 48.869867 ]
})();

import json
import urllib.request

api_key = '<YOUR API KEY>'
query = "https://api.geocode.earth/v1/autocomplete?" \
        "api_key="+api_key+"&"\
        "boundary.country=FRA,DE&" \
        "text=laduree"

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

print(response) # print the entire response

print(response['features'][0]['properties']['name'])      # Ladurée
print(response['features'][0]['properties']['label'])     # Ladurée, Paris, France
print(response['features'][0]['geometry']['coordinates']) # [ 2.321311, 48.869867 ]

Restrict results by parent ID #

Try in Explorer

Every record returned by Geocode Earth includes a GID, or global ID. These IDs can be used to filter results to areas smaller than countries, and/or areas with shapes not well represented by rectangular bounding boxes.

Only Global IDs starting with whosonfirst are suitable for use with boundary.gid.

For more info, read our guidelines on Global IDs.

For example, to find locations of the Bean There Coffee Company, limited only to Cape Town, South Africa, use boundary.gid=whosonfirst:locality:101928027.

We've securely inserted your Geocode Earth API key in the example code below.

Shell Ruby Node.js Python

curl --get https://api.geocode.earth/v1/autocomplete \
  -d api_key=<YOUR API KEY> \
  -d boundary.gid=whosonfirst:locality:101928027 \
  -d text=bean+there

require 'net/http'
require 'json'

api_key = '<YOUR API KEY>'
query = "https://api.geocode.earth/v1/autocomplete?"\
        "api_key=#{api_key}&"\
        "boundary.gid=whosonfirst:locality:101928027&" \
        "text=bean there"

http_response = Net::HTTP.get_response(URI(query.gsub(' ', '+')))
response = JSON.parse(http_response.body)

puts response # print the entire response

puts response['features'][0]['properties']['name']      # Bean There
puts response['features'][0]['properties']['label']     # Bean There, Cape Town, South Africa
puts response['features'][0]['geometry']['coordinates'] # [ 18.417273, -33.922723 ]

const api_key = '<YOUR API KEY>';
const url = new URL('https://api.geocode.earth/v1/autocomplete');
url.searchParams.set('api_key', api_key);
url.searchParams.set('boundary.gid', 'whosonfirst:locality:101928027');
url.searchParams.set('text', 'bean there');

(async () => {
  const response = await fetch(url);
  const data = await response.json();
  console.log(data); // print the entire response

  console.log(data.features[0].properties.name);      // Bean There
  console.log(data.features[0].properties.label);     // Bean There, Cape Town, WC, South Africa
  console.log(data.features[0].geometry.coordinates); // [ 18.417273, -33.922723 ]
})();

import json
import urllib.request

api_key = '<YOUR API KEY>'
query = "https://api.geocode.earth/v1/autocomplete?" \
        "api_key="+api_key+"&"\
        "boundary.gid=whosonfirst:locality:101928027&" \
        "text=bean there".replace(' ', '+')

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

print(response) # print the entire response

print(response['features'][0]['properties']['name'])      # Bean There
print(response['features'][0]['properties']['label'])     # Bean There, Cape Town, South Africa
print(response['features'][0]['geometry']['coordinates']) # [ 18.417273, -33.922723 ]

Filter results by data layer #

Try in Explorer

Filtering results by layer can be useful to return only particular types of results.

For example, to return only Countries, use layers=country,dependency.

Layers can be removed from results by prefixing the layer with a -. For example, layers=-address would allow results from all layers except the address layer.

We've securely inserted your Geocode Earth API key in the example code below.

Shell Ruby Node.js Python

curl --get https://api.geocode.earth/v1/autocomplete \
  -d api_key=<YOUR API KEY> \
  -d layers=country,dependency \
  -d text=new+zealand

require 'net/http'
require 'json'

api_key = '<YOUR API KEY>'
query = "https://api.geocode.earth/v1/autocomplete?"\
        "api_key=#{api_key}&"\
        "layers=country,dependency&" \
        "text=new zealand"

http_response = Net::HTTP.get_response(URI(query.gsub(' ', '+')))
response = JSON.parse(http_response.body)

puts response # print the entire response

puts response['features'][0]['properties']['label']     # New Zealand

const api_key = '<YOUR API KEY>';
const url = new URL('https://api.geocode.earth/v1/autocomplete');
url.searchParams.set('api_key', api_key);
url.searchParams.set('layers', 'country,dependency');
url.searchParams.set('text', 'new zealand');

(async () => {
  const response = await fetch(url);
  const data = await response.json();
  console.log(data); // print the entire response

  console.log(data.features[0].properties.label);     // New Zealand
})();

import json
import urllib.request

api_key = '<YOUR API KEY>'
query = "https://api.geocode.earth/v1/autocomplete?" \
        "api_key="+api_key+"&"\
        "layers=country,dependency&" \
        "text=new zealand".replace(' ', '+')

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

print(response) # print the entire response

print(response['features'][0]['properties']['label'])     # New Zealand

Change the number of results returned #

Try in Explorer

By default, a maximum of 10 results are returned. Use the size parameter to change this, up to a maximum of 40.

For example, size=40 returns up to 40 results. Values above 40 are treated as 40, and a warning is added to the response.

size sets an upper limit on the number of results. The filters above are applied first, so a query with a strict filter such as layers=venue or a small bounding box may return fewer results than requested.

Structured Geocoding API Reverse Geocoding API