Geocoding Quickstart Guide

This guide will help you get started with Geocode Earth quickly, with brief introductions to the core functionality of the service.

Forward geocoding #

The simplest and most common type of geocoding is forward geocoding. Geocode Earth supports forward geocoding through the search endpoint and the text parameter.

Search for a city #

Shell Ruby Node.js Python
api_key='<YOUR API KEY>'

curl --get https://api.geocode.earth/v1/search \
  -d api_key=$api_key \
  -d text=London

require 'net/http'
require 'json'

api_key = '<YOUR API KEY>'
query = "https://api.geocode.earth/v1/search?"\
        "api_key=#{api_key}&"\
        "text=London"
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']      # London
puts response['features'][0]['properties']['label']     # London, England, United Kingdom
puts response['features'][0]['geometry']['coordinates'] # [ -0.099076, 51.509648 ]

const https = require('https');

const api_key = '<YOUR API KEY>';
const query = 'https://api.geocode.earth/v1/search?' +
              `api_key=${api_key}&` +
              'text=London';

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']);      // London
    console.log(response['features'][0]['properties']['label']);     // London, England, United Kingdom
    console.log(response['features'][0]['geometry']['coordinates']); // [ -0.099076, 51.509648 ]
  });
}).end();

import json
import urllib.request

api_key = '<YOUR API KEY>'
query = "https://api.geocode.earth/v1/search?" \
        "api_key="+api_key+"&"\
        "text=London"

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

print(response) # print the entire response

print(response['features'][0]['properties']['name'])      # London
print(response['features'][0]['properties']['label'])     # London, England, United Kingdom
print(response['features'][0]['geometry']['coordinates']) # [ -0.099076, 51.509648 ]

Geocode Earth responses are GeoJSON, so many tools can work with them out of the box:

Response
{
  "type": "FeatureCollection",
  "features": [{
    "type": "Feature",
    "geometry": {
      "type": "Point",
      "coordinates": [
        -0.099076,
        51.509648
      ]
    },
    "properties": {
      "id": "101750367",
      "gid": "whosonfirst:locality:101750367",
      "layer": "locality",
      "source": "whosonfirst",
      "source_id": "101750367",
      "name": "London",
      "confidence": 1,
      "match_type": "exact",
      "accuracy": "centroid",
      "country": "United Kingdom",
      "country_gid": "whosonfirst:country:85633159",
      "country_a": "GBR",
      "macroregion": "England",
      "macroregion_gid": "whosonfirst:macroregion:404227469",
      "region": "Greater London",
      "region_gid": "whosonfirst:region:1360698645",
      "locality": "London",
      "locality_gid": "whosonfirst:locality:101750367",
      "continent": "Europe",
      "continent_gid": "whosonfirst:continent:102191581",
      "label": "London, England, United Kingdom"
    },
    "bbox": [
      -0.510375069372,
      51.2867601625,
      0.334015563634,
      51.6918741161
    ]
  }]
}

The most generally useful pieces of data in the response are:

  • label: A full placetype label ready for display, that takes into account local formatting customs
  • name: The name of the particular result, without information about the city, country, etc
  • coordinates: This is inside the geometry property, and includes the latitude and longitude for the record
  • layer: The placetype of the record. This might be venue, address, locality or one of many other options

For full details about all response properties, see our response format reference.

Search for an address #

Addresses can be geocoded using the same text parameter. If the address data is already split into multiple fields, use the structured geocoding endpoint.

Shell Ruby Node.js Python
api_key='<YOUR API KEY>'

curl --get https://api.geocode.earth/v1/search \
  -d api_key=$api_key \
  -d "text=2+Macquarie+Street+Sydney"

require 'net/http'
require 'json'

api_key = '<YOUR API KEY>'
query = "https://api.geocode.earth/v1/search?"\
        "api_key=#{api_key}&"\
        "text=2 Macquarie Street, Sydney"
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']      # 2 Macquarie Street
puts response['features'][0]['properties']['label']     # 2 Macquarie Street, Sydney, NSW, Australia
puts response['features'][0]['geometry']['coordinates'] # [ 151.215353, -33.860194 ]

const https = require('https');

const api_key = '<YOUR API KEY>';
const query = 'https://api.geocode.earth/v1/search?' +
              `api_key=${api_key}&` +
              'text=2 Macquarie Street Sydney'.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']);      // 2 Macquarie Street
    console.log(response['features'][0]['properties']['label']);     // 2 Macquarie Street, Sydney, NSW, Australia
    console.log(response['features'][0]['geometry']['coordinates']); // [ 151.215353, -33.860194 ]
  });
}).end();

import json
import urllib.request

api_key = '<YOUR API KEY>'
query = "https://api.geocode.earth/v1/search?" \
        "api_key="+api_key+"&"\
        "text=2 Macquarie Street Sydney".replace(' ', '+')

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

print(response) # print the entire response

print(response['features'][0]['properties']['name'])      # 2 Macquarie Street
print(response['features'][0]['properties']['label'])     # 2 Macquarie Street, Sydney, NSW, Australia
print(response['features'][0]['geometry']['coordinates']) # [ 151.215353, -33.860194 ]

There are several address specific properties, such as housenumber, street, and postalcode.

Response
{
  "type": "FeatureCollection",
  "features": [{
    "type": "Feature",
    "geometry": {
      "type": "Point",
      "coordinates": [
        151.215353,
        -33.860194
      ]
    },
    "properties": {
      "layer": "address",
      "source": "openaddresses",
      "name": "2A Macquarie Street",
      "housenumber": "2A",
      "street": "Macquarie Street",
      "postalcode": "2000",
      "confidence": 1,
      "match_type": "exact",
      "accuracy": "point",
      "country": "Australia",
      "country_a": "AUS",
      "region": "New South Wales",
      "region_a": "NSW",
      "county_a": "SY",
      "locality": "Sydney",
      "label": "2A Macquarie Street, Sydney, NSW, Australia"
    }
  }]
}

Some properties removed for brevity

Autocomplete user input #

The Autocomplete endpoint has the same interface as search, but it supports partial inputs (such as those that come from a human still typing). It’s designed for quick, low latency responses so that you can build snappy, responsive user interfaces.

To find London, an autocomplete query for lond will work just as well as london. Note that the search endpoint would, by design, return the town of Lond, Pakistan.

Shell Ruby Node.js Python
api_key='<YOUR API KEY>'

curl --get https://api.geocode.earth/v1/autocomplete \
  -d api_key=$api_key \
  -d text=lond

require 'net/http'
require 'json'

api_key = '<YOUR API KEY>'
query = "https://api.geocode.earth/v1/autocomplete?"\
        "api_key=#{api_key}&"\
        "text=lond"
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']      # London
puts response['features'][0]['properties']['label']     # London, England, United Kingdom
puts response['features'][0]['geometry']['coordinates'] # [ -0.099076, 51.509648 ]

const https = require('https');

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

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']);      // London
    console.log(response['features'][0]['properties']['label']);     // London, England, United Kingdom
    console.log(response['features'][0]['geometry']['coordinates']); // [ -0.099076, 51.509648 ]
  });
}).end();

import json
import urllib.request

api_key = '<YOUR API KEY>'
query = "https://api.geocode.earth/v1/autocomplete?" \
        "api_key="+api_key+"&"\
        "text=lond"

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

print(response) # print the entire response

print(response['features'][0]['properties']['name'])      # London
print(response['features'][0]['properties']['label'])     # London, England, United Kingdom
print(response['features'][0]['geometry']['coordinates']) # [ -0.099076, 51.509648 ]

Reverse geocode a coordinate #

Reverse geocoding answers the question: “What is at this exact location?”.

The most common way to use is to provide a latitude and longitude via the point.lat and point.lon parameters. This will generally return an address or point of interest (POI):

Shell Ruby Node.js Python
api_key='<YOUR API KEY>'

curl --get https://api.geocode.earth/v1/reverse \
  -d api_key=$api_key \
  -d point.lat=40.748163 \
  -d point.lon=-73.984996

require 'net/http'
require 'json'

api_key = '<YOUR API KEY>'
query = "https://api.geocode.earth/v1/reverse?"\
        "api_key=#{api_key}&"\
        "point.lat=40.748163&" \
        "point.lon=-73.984996"
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']      # Empire State Building
puts response['features'][0]['properties']['label']     # Empire State Building, Manhattan, New York, NY, USA
puts response['features'][0]['geometry']['coordinates'] # [ -73.984996, 40.748163 ]

const https = require('https');

const api_key = '<YOUR API KEY>';
const query = 'https://api.geocode.earth/v1/reverse?' +
              `api_key=${api_key}&` +
              'point.lat=40.748163&' +
              'point.lon=-73.984996'

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']);      // Empire State Building
    console.log(response['features'][0]['properties']['label']);     // Empire State Building, Manhattan, New York, NY, USA
    console.log(response['features'][0]['geometry']['coordinates']); // [ -73.984996, 40.748163 ]
  });
}).end();

import json
import urllib.request

api_key = '<YOUR API KEY>'
query = "https://api.geocode.earth/v1/reverse?" \
        "api_key="+api_key+"&"\
        "point.lat=40.748163&" \
        "point.lon=-73.984996"

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

print(response) # print the entire response

print(response['features'][0]['properties']['name'])      # Empire State Building
print(response['features'][0]['properties']['label'])     # Empire State Building, Manhattan, New York, NY, USA
print(response['features'][0]['geometry']['coordinates']) # [ -73.984996, 40.748163 ]
Response
{
  "type": "FeatureCollection",
  "features": [{
    "type": "Feature",
    "geometry": {
      "type": "Point",
      "coordinates": [ -73.984996, 40.748163 ]
    },
    "properties": {
      "gid": "openstreetmap:venue:node/2709306673",
      "layer": "venue",
      "source": "openstreetmap",
      "name": "Empire State Building",
      "housenumber": "350",
      "street": "5th Avenue",
      "postalcode": "10118",
      "confidence": 1,
      "distance": 0,
      "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",
      "label": "Empire State Building, Manhattan, New York, NY, USA"
    }
  },
  {
    "type": "Feature",
    "geometry": {
      "type": "Point",
      "coordinates": [ -73.984996, 40.748163 ]
    },
    "properties": {
      "gid": "openstreetmap:address:node/2709306673",
      "layer": "address",
      "source": "openstreetmap",
      "name": "350 5th Avenue",
      "housenumber": "350",
      "street": "5th Avenue",
      "postalcode": "10118",
      "confidence": 1,
      "distance": 0,
      "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": "350 5th Avenue, Manhattan, New York, NY, USA"
    }
  }]
}

Reverse geocode to a geographic area (point in polygon) #

The Reverse endpoint can also answer the question: “what is this point contained within?”.

The answer will be one of the many administrative areas supported by Geocode Earth such as locality (city), neighbourhood, country, or continent.

Reverse geocoding requests that do not return an address or venue will automatically return administrative area results. Alternatively, you can specify which type of administrative area to return explicitly with the layers parameter.

For example, to get the city at a given coordinate, use layers=locality

Shell Ruby Node.js Python
api_key='<YOUR API KEY>'

curl --get https://api.geocode.earth/v1/reverse \
  -d api_key=$api_key \
  -d point.lat=40.748163 \
  -d point.lon=-73.984996 \
  -d layers=locality

require 'net/http'
require 'json'

api_key = '<YOUR API KEY>'
query = "https://api.geocode.earth/v1/reverse?"\
        "api_key=#{api_key}&"\
        "point.lat=40.748163&" \
        "point.lon=-73.984996&" \
        "layers=locality"
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']      # New York
puts response['features'][0]['properties']['label']     # New York, NY, USA
puts response['features'][0]['geometry']['coordinates'] # [ -73.9708, 40.68295 ]

const https = require('https');

const api_key = '<YOUR API KEY>';
const query = 'https://api.geocode.earth/v1/reverse?' +
              `api_key=${api_key}&` +
              'point.lat=40.748163&' +
              'point.lon=-73.984996&' +
              'layers=locality';

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']);      // New York
    console.log(response['features'][0]['properties']['label']);     // New York, NY, USA
    console.log(response['features'][0]['geometry']['coordinates']); // [ -73.9708, 40.68295 ]
  });
}).end();

import json
import urllib.request

api_key = '<YOUR API KEY>'
query = "https://api.geocode.earth/v1/reverse?" \
        "api_key="+api_key+"&"\
        "point.lat=40.748163&" \
        "point.lon=-73.984996&" \
        "layers=locality"

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

print(response) # print the entire response

print(response['features'][0]['properties']['name'])      # New York
print(response['features'][0]['properties']['label'])     # New York, NY
print(response['features'][0]['geometry']['coordinates']) # [ -73.9708, 40.68295 ]

This gives you just the city of New York.

Next steps #

That’s it for the brief overview, take a look at the full documentation for our search, autocomplete, and reverse endpoints to learn more.