Search API

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

The Search API endpoint performs forward geocoding: converting text that represents an address or place name into coordinates.

Geocode Earth supports geocoding addresses, points of interests, streets, and numerous administrative areas such as neighborhoods, cities, counties, states (referred to as regions), countries, and continents.

The search endpoint works best with complete inputs. For input that might be partially complete (because, for example it comes from a human typing), use the autocomplete endpoint.

Basic usage #

To perform forward geocoding with the search endpoint, use the text parameter to specify what to search for:

Shell Ruby Node.js Python
curl --get https://api.geocode.earth/v1/search \
  -d api_key=<YOUR API KEY> \
  -d "text=476+5th+Avenue,+New+York,+NY+10018"

require 'net/http'
require 'json'

api_key = '<YOUR API KEY>'
query = "https://api.geocode.earth/v1/search?"\
        "api_key=#{api_key}&"\
        "text=476 5th Avenue, New York, NY 10018"
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']      # 476 5th Avenue
puts response['features'][0]['properties']['label']     # 476 5th Avenue, New York, NY, USA
puts response['features'][0]['geometry']['coordinates'] # [ -73.981905, 40.753664 ]

const https = require('https');

const api_key = '<YOUR API KEY>';
const query = 'https://api.geocode.earth/v1/search?' +
              `api_key=${api_key}&` +
              'text=476 5th Avenue, New York, NY 10018'.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']);      // 476 5th Avenue
    console.log(response['features'][0]['properties']['label']);     // 476 5th Avenue, New York, NY, USA
    console.log(response['features'][0]['geometry']['coordinates']); // [ -73.981905, 40.753664 ]
  });
}).end();

import json
import urllib.request

api_key = '<YOUR API KEY>'
query = "https://api.geocode.earth/v1/search?" \
        "api_key="+api_key+"&"\
        "text=476 5th Avenue, New York, NY 10018".replace(' ', '+')

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

print(response) # print the entire response

print(response['features'][0]['properties']['name'])      # 476 5th Avenue
print(response['features'][0]['properties']['label'])     # 476 5th Avenue, New York, NY, USA
print(response['features'][0]['geometry']['coordinates']) # [ -73.981905, 40.753664 ]
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"
    }
  }]
}

Filtering parameters #

The search endpoint supports all forward geocoding filtering parameters.

For example, you might want to limit results to the country of Canada, and exclude all results except addresses.

Shell Ruby Node.js Python
curl --get https://api.geocode.earth/v1/search \
  -d api_key=<YOUR API KEY> \
  -d boundary.country=CA \
  -d layers=address \
  -d "text=317+Dundas+St+W,+Toronto,+ON+M5T+1G4"

require 'net/http'
require 'json'

api_key = '<YOUR API KEY>'
query = "https://api.geocode.earth/v1/search?"\
        "api_key=#{api_key}&"\
        "boundary.country=CA&"\
        "layers=address&"\
        "text=317 Dundas St W, Toronto, ON M5T 1G4"
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']      # 317 Dundas Street West
puts response['features'][0]['properties']['label']     # 317 Dundas Street West, Toronto, ON, Canada
puts response['features'][0]['geometry']['coordinates'] # [ -79.392539, 43.653644 ]

const https = require('https');

const api_key = '<YOUR API KEY>';
const query = 'https://api.geocode.earth/v1/search?' +
              `api_key=${api_key}&`  +
              'boundary.country=CA&' +
              'layers=address&'      +
              'text=317 Dundas St W, Toronto, ON M5T 1G4'.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']);      // 317 Dundas Street West
    console.log(response['features'][0]['properties']['label']);     // 317 Dundas Street West, Toronto, ON, Canada
    console.log(response['features'][0]['geometry']['coordinates']); // [ -79.392539, 43.653644 ]
  });
}).end();

import json
import urllib.request

api_key = '<YOUR API KEY>'
query = "https://api.geocode.earth/v1/search?" \
        "api_key="+api_key+"&"\
        "boundary.country=CA&"\
        "layers=address&"\
        "text=317 Dundas St W, Toronto, ON M5T 1G4".replace(' ', '+')

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

print(response) # print the entire response

print(response['features'][0]['properties']['name'])      # 317 Dundas Street West
print(response['features'][0]['properties']['label'])     # 317 Dundas Street West, Toronto, ON, Canada

print(response['features'][0]['geometry']['coordinates']) # [ -79.392539, 43.653644 ]