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:

Use a lat/lon 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:

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 https = require('https');

const api_key = '<YOUR API KEY>';
const query = 'https://api.geocode.earth/v1/autocomplete?' +
              `api_key=${api_key}&` +
              'focus.point.lat=40.7566&' +
              'focus.point.lon=-73.9859&' +
              'text=starbucks'

const req = https.get(query, (res) => {
  let body = '';
  res.on('data', data => { body += data; });

  res.on('end', () => {
    const response = JSON.parse(body);
    console.log(response); // print the entire response

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

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 #

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 one or more countries #

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.

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=starbucks

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=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, Aachen, Germany
puts response['features'][0]['geometry']['coordinates'] # [ 6.083346, 50.776514 ]

const https = require('https');

const api_key = '<YOUR API KEY>';
const query = 'https://api.geocode.earth/v1/autocomplete?' +
              `api_key=${api_key}&` +
              'boundary.country=FRA,DE&' +
              'text=starbucks'

const req = https.get(query, (res) => {
  let body = '';
  res.on('data', data => { body += data; });

  res.on('end', () => {
    const response = JSON.parse(body);
    console.log(response); // print the entire response

    console.log(response['features'][0]['properties']['name']);      // Starbucks
    console.log(response['features'][0]['properties']['label']);     // Starbucks, Aachen, Germany
    console.log(response['features'][0]['geometry']['coordinates']); // [ 6.083346, 50.776514 ]
  });
}).end();

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=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, Aachen, Germany
print(response['features'][0]['geometry']['coordinates']) # [ 6.083346, 50.776514 ]

Restrict results by parent ID #

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.

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 https = require('https');

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

const req = https.get(query, (res) => {
  let body = '';
  res.on('data', data => { body += data; });

  res.on('end', () => {
    const response = JSON.parse(body);
    console.log(response); // print the entire response

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

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 #

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.

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 https = require('https');

const api_key = '<YOUR API KEY>';
const query = 'https://api.geocode.earth/v1/autocomplete?' +
              `api_key=${api_key}&` +
              'layers=country,dependency&' +
              'text=new zealand'.replace(' ', '+');

const req = https.get(query, (res) => {
  let body = '';
  res.on('data', data => { body += data; });

  res.on('end', () => {
    const response = JSON.parse(body);
    console.log(response); // print the entire response

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

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