Place API
https://api.geocode.earth/v1/place
The Place API returns detailed information about a specific record, using a Global ID (GID) returned from another endpoint.
You can use this endpoint to fetch full details of a record. This allows you to, for example, store only the GID in your own database, and retrieve more information on demand.
GIDs are included in every result from the search, autocomplete, structured search, and reverse geocoding endpoints.
Basic usage #
The place endpoint takes a single parameter, ids, which is a comma separated list of Global IDs. Every record returned by Geocode Earth includes a unique Global ID.
We've securely inserted your Geocode Earth API key in the example code below.
Sign up for a free trial and we'll put your API key in the code below so you can get started right away!
curl --get https://api.geocode.earth/v1/place \
-d api_key=<YOUR API KEY> \
-d ids=whosonfirst:locality:101751119
require 'net/http'
require 'json'
api_key = '<YOUR API KEY>'
query = "https://api.geocode.earth/v1/place?"\
"api_key=#{api_key}&"\
"ids=whosonfirst:locality:101751119"
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'] # Paris
puts response['features'][0]['properties']['label'] # Paris, France
puts response['features'][0]['geometry']['coordinates'] # [ 2.347, 48.859 ]
const https = require('https');
const api_key = '<YOUR API KEY>';
const query = 'https://api.geocode.earth/v1/place?' +
`api_key=${api_key}&` +
'ids=whosonfirst:locality:101751119';
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']); // Paris
console.log(response['features'][0]['properties']['label']); // Paris, France
console.log(response['features'][0]['geometry']['coordinates']); // [ 2.347, 48.859 ]
});
}).end();
import json
import urllib.request
api_key = '<YOUR API KEY>'
query = "https://api.geocode.earth/v1/place?" \
"api_key="+api_key+"&"\
"ids=whosonfirst:locality:101751119"
response = json.load(urllib.request.urlopen(query))
print(response) # print the entire response
print(response['features'][0]['properties']['name']) # Paris
print(response['features'][0]['properties']['label']) # Paris, France
print(response['features'][0]['geometry']['coordinates']) # [ 2.347, 48.859 ]
Response
{
"type": "FeatureCollection",
"features": [{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
2.342865,
48.858705
]
},
"properties": {
"gid": "whosonfirst:locality:101751119",
"layer": "locality",
"source": "whosonfirst",
"source_id": "101751119",
"name": "Paris",
"country": "France",
"country_gid": "whosonfirst:country:85633147",
"country_a": "FRA",
"macroregion": "Ile-of-France",
"macroregion_gid": "whosonfirst:macroregion:404227465",
"macroregion_a": "IF",
"region": "Paris",
"region_gid": "whosonfirst:region:85683497",
"region_a": "VP",
"localadmin": "Paris",
"localadmin_gid": "whosonfirst:localadmin:1159322569",
"locality": "Paris",
"locality_gid": "whosonfirst:locality:101751119",
"label": "Paris, France"
}
}]
}
Looking up multiple records #
Multiple GIDs can be provided as a comma-separated list, returning all matching records in a single request.
We've securely inserted your Geocode Earth API key in the example code below.
Sign up for a free trial and we'll put your API key in the code below so you can get started right away!
curl --get https://api.geocode.earth/v1/place \
-d api_key=<YOUR API KEY> \
-d ids=whosonfirst:locality:101751119,whosonfirst:locality:101750367
require 'net/http'
require 'json'
api_key = '<YOUR API KEY>'
gids = [
'whosonfirst:locality:101751119', # Paris, France
'whosonfirst:locality:101750367', # London, United Kingdom
]
query = "https://api.geocode.earth/v1/place?"\
"api_key=#{api_key}&"\
"ids=#{gids.join(',')}"
http_response = Net::HTTP.get_response(URI(query))
response = JSON.parse(http_response.body)
response['features'].each do |feature|
puts feature['properties']['label']
end
# Paris, France
# London, England, United Kingdom
const https = require('https');
const api_key = '<YOUR API KEY>';
const gids = [
'whosonfirst:locality:101751119', // Paris, France
'whosonfirst:locality:101750367', // London, United Kingdom
];
const query = 'https://api.geocode.earth/v1/place?' +
`api_key=${api_key}&` +
`ids=${gids.join(',')}`;
const req = https.get(query, (res) => {
let body = '';
res.on('data', data => { body += data; });
res.on('end', () => {
const response = JSON.parse(body);
response['features'].forEach(feature => {
console.log(feature['properties']['label']);
});
// Paris, France
// London, England, United Kingdom
});
}).end();
import json
import urllib.request
api_key = '<YOUR API KEY>'
gids = [
'whosonfirst:locality:101751119', # Paris, France
'whosonfirst:locality:101750367', # London, United Kingdom
]
query = "https://api.geocode.earth/v1/place?" \
"api_key="+api_key+"&"\
"ids="+",".join(gids)
response = json.load(urllib.request.urlopen(query))
for feature in response['features']:
print(feature['properties']['label'])
# Paris, France
# London, England, United Kingdom
Response
{
"type": "FeatureCollection",
"features": [{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
2.342865,
48.858705
]
},
"properties": {
"gid": "whosonfirst:locality:101751119",
"layer": "locality",
"source": "whosonfirst",
"source_id": "101751119",
"name": "Paris",
"country": "France",
"country_gid": "whosonfirst:country:85633147",
"country_a": "FRA",
"macroregion": "Ile-of-France",
"macroregion_gid": "whosonfirst:macroregion:404227465",
"macroregion_a": "IF",
"region": "Paris",
"region_gid": "whosonfirst:region:85683497",
"region_a": "VP",
"localadmin": "Paris",
"localadmin_gid": "whosonfirst:localadmin:1159322569",
"locality": "Paris",
"locality_gid": "whosonfirst:locality:101751119",
"label": "Paris, France"
}
}, {
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
-0.099076,
51.509648
]
},
"properties": {
"gid": "whosonfirst:locality:101750367",
"id": "101750367",
"layer": "locality",
"source": "whosonfirst",
"source_id": "101750367",
"country_code": "GB",
"name": "London",
"accuracy": "centroid",
"country": "United Kingdom",
"country_gid": "whosonfirst:country:85633159",
"country_a": "GBR",
"macroregion": "England",
"macroregion_gid": "whosonfirst:macroregion:404227469",
"region": "London",
"region_gid": "whosonfirst:region:1880762729",
"locality": "London",
"locality_gid": "whosonfirst:locality:101750367",
"label": "London, England, United Kingdom"
}
}]
}
Stable and unstable Global IDs #
Records that represent administrative areas in Geocode Earth, like cities, countries, etc have stable IDs. This means you can trust that the ID value will not change, even over weeks, months, or years.
For example, whosonfirst:locality:101751119 is the GID for Paris, France, so a query for that GID will always return information about Paris.
Unstable Global IDs #
Records such as addresses and venues generally do not contain stable IDs. You can fetch details via the place endpoint, but the same query weeks or months later may result in either a different record or an empty response as that record may no longer exist.
See Datasets without stable IDs for more details.