Structured Geocoding API

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

Use the Structured Geocoding API endpoint when you have data that has already been split into multiple fields such as address, city, and postal code.

Unlike the Search endpoint, which accepts only a single text parameter, the structured endpoint accepts many parameters:

address neighbourhood borough locality county region postalcode country

Each of these parameters roughly corresponds to the data layer of the same name. At least one parameter must be specified, but any combination is valid.

Finding an address with structured data #

If you have data in a spreadsheet or CSV, you can use the structured geocoding endpoint to geocode the addresses more accurately than would be possible with the search endpoint.

For example, you might have the following data:

Rows from the data above can be mapped to parameters on the structured geocoding endpoint:

curl --get https://api.geocode.earth/v1/search/structured \
  -d api_key=<YOUR API KEY> \
  -d "address=10+Downing+St" \
  -d "locality=London" \
  -d "postalcode=SW1A+2AA" \
  -d "country=GB" > response.json

jq .features[0].properties.name      response.json # 10 Downing Street
jq .features[0].properties.label     response.json # 10 Downing Street, London, England, United Kingdom
jq .features[0].geometry.coordinates response.json # [-0.127636, 51.50328]

require 'net/http'
require 'json'

api_key = '<YOUR API KEY>'
query = "https://api.geocode.earth/v1/search/structured?"\
        "api_key=#{api_key}&"\
        "address=10 Downing St&"\
        "locality=London&"\
        "postalcode=SW1A 2AA&"\
        "country=GB".gsub(' ','+')
http_response = Net::HTTP.get_response(URI(query))
response = JSON.parse(http_response.body)

puts response['features'][0]['properties']['name']      # 10 Downing Street
puts response['features'][0]['properties']['label']     # 10 Downing Street, London, England, United Kingdom
puts response['features'][0]['geometry']['coordinates'] # [-0.127636, 51.50328]

const https = require('https');

const api_key = '<YOUR API KEY>';
const query = 'https://api.geocode.earth/v1/search/structured?' +
              `api_key=${api_key}&` +
              'address=10 Downing St&' +
              'locality=London&' +
              'country=GB';

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

  res.on('end', () => {
    const response = JSON.parse(body);

    console.log(response['features'][0]['properties']['name']);      // 10 Downing Street
    console.log(response['features'][0]['properties']['label']);     // 10 Downing Street, London, England, United Kingdom
    console.log(response['features'][0]['geometry']['coordinates']); // [-0.127636, 51.50328]
  });
}).end();

import json
import urllib.request

api_key = '<YOUR API KEY>'
query = "https://api.geocode.earth/v1/search/structured?" \
        "api_key="+api_key+"&"\
        "address=10 Downing St&"\
        "locality=London&"\
        "country=GB".replace(' ', '+')

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

print(response['features'][0]['properties']['name'])      # 10 Downing Street
print(response['features'][0]['properties']['label'])     # 10 Downing Street, London, England, United Kingdom
print(response['features'][0]['geometry']['coordinates']) # [-0.127636, 51.50328]

House numbers and street names #

If your data includes housenumbers and streetnames in separate columns, you must combine them into a single address field. Where possible, you should do this in whatever local format is appropriate for the address. However, Geocode Earth can generally handle format variations, especially non-standard ordering of housenumber and streetname.

For example, when looking for the Reichstag building in Berlin, either 1 Platz der Republik or Platz der Republic 1 will work, even though the latter is the preferred local format.

Filtering #

The structured endpoint supports all the same filtering options as other endpoints.

Note that the boundary.country filtering parameter only supports 2 and 3 digit ISO 3166-1 codes, while the country parameter on the structured search endpoint supports both codes and complete names. When used with an ISO 3166-1 code, the two parameters have equivalent behavior.