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 api_key = '<YOUR API KEY>';
const url = new URL('https://api.geocode.earth/v1/search');
url.searchParams.set('api_key', api_key);
url.searchParams.set('text', '476 5th Avenue, New York, NY 10018');

(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);      // 476 5th Avenue
  console.log(data.features[0].properties.label);     // 476 5th Avenue, New York, NY, USA
  console.log(data.features[0].geometry.coordinates); // [ -73.981905, 40.753664 ]
})();

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": "2 Macquarie Street",
      "housenumber": "2",
      "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": "2 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 api_key = '<YOUR API KEY>';
const url = new URL('https://api.geocode.earth/v1/search');
url.searchParams.set('api_key', api_key);
url.searchParams.set('boundary.country', 'CA');
url.searchParams.set('layers', 'address');
url.searchParams.set('text', '317 Dundas St W, Toronto, ON M5T 1G4');

(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);      // 317 Dundas Street West
  console.log(data.features[0].properties.label);     // 317 Dundas Street West, Toronto, ON, Canada
  console.log(data.features[0].geometry.coordinates); // [ -79.392539, 43.653644 ]
})();

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 ]