Geocoding
Convert human-readable addresses into geographic coordinates (geocoding) and convert coordinates back into addresses (reverse geocoding). Powered by OpenStreetMap via the Nominatim API.
Overview
Use Cases
- Place pins on a map from a user-supplied address
- Convert GPS coordinates to a readable address for display
- Validate and normalise addresses
- Power location-aware search and filtering features
Features
Forward geocoding (address to lat/lon)
Reverse geocoding (lat/lon to address)
Worldwide coverage via OpenStreetMap data
Results cached for 24 hours for fast repeated lookups
API Endpoints
Geocode Address
Converts a free-text address into latitude and longitude coordinates.
GET
https://api.requiems.xyz/v1/places/geocode
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| address | string |
Required | The address to geocode (street, city, country, or any combination) |
Try it out
Live DemoRequest
The address to geocode (street, city, country, or any combination)
Sending request...
Response Fields
| Field | Type | Description |
|---|---|---|
| address | string |
Full display name of the matched location |
| city | string |
City or town of the matched location |
| country | string |
ISO 3166-1 alpha-2 country code (uppercase) |
| lat | number |
Latitude of the matched location |
| lon | number |
Longitude of the matched location |
Code Examples
curl "https://api.requiems.xyz/v1/places/geocode?address=1600+Pennsylvania+Ave+NW" \
-H "requiems-api-key: YOUR_API_KEY"import requests
url = "https://api.requiems.xyz/v1/places/geocode"
headers = {"requiems-api-key": "YOUR_API_KEY"}
response = requests.get(url, params={"address": "1600 Pennsylvania Ave NW"}, headers=headers)
data = response.json()
print(data["data"]["lat"], data["data"]["lon"])const params = new URLSearchParams({ address: '1600 Pennsylvania Ave NW' });
const response = await fetch(
`https://api.requiems.xyz/v1/places/geocode?${params}`,
{ headers: { 'requiems-api-key': 'YOUR_API_KEY' } }
);
const data = await response.json();
console.log(data.data.lat, data.data.lon);require 'net/http'
require 'json'
uri = URI('https://api.requiems.xyz/v1/places/geocode')
uri.query = URI.encode_www_form(address: '1600 Pennsylvania Ave NW')
request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
data = JSON.parse(response.body)
puts "#{data['data']['lat']}, #{data['data']['lon']}"Error Responses
not_found
No results found for the given address.
upstream_error
The geocoding service is temporarily unavailable.
bad_request
The address parameter is missing.
Reverse Geocode
Converts geographic coordinates into a human-readable address.
GET
https://api.requiems.xyz/v1/places/reverse-geocode
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| lat | number |
Required | Latitude of the location (-90 to 90) |
| lon | number |
Required | Longitude of the location (-180 to 180) |
Try it out
Live DemoRequest
Latitude of the location (-90 to 90)
Longitude of the location (-180 to 180)
Sending request...
Response Fields
| Field | Type | Description |
|---|---|---|
| lat | number |
Latitude as provided in the request |
| lon | number |
Longitude as provided in the request |
| address | string |
Full display name of the location at the given coordinates |
| city | string |
City or town at the given coordinates |
| country | string |
ISO 3166-1 alpha-2 country code (uppercase) |
Code Examples
curl "https://api.requiems.xyz/v1/places/reverse-geocode?lat=38.8977&lon=-77.0365" \
-H "requiems-api-key: YOUR_API_KEY"import requests
url = "https://api.requiems.xyz/v1/places/reverse-geocode"
headers = {"requiems-api-key": "YOUR_API_KEY"}
response = requests.get(url, params={"lat": 38.8977, "lon": -77.0365}, headers=headers)
data = response.json()
print(data["data"]["address"])const params = new URLSearchParams({ lat: 38.8977, lon: -77.0365 });
const response = await fetch(
`https://api.requiems.xyz/v1/places/reverse-geocode?${params}`,
{ headers: { 'requiems-api-key': 'YOUR_API_KEY' } }
);
const data = await response.json();
console.log(data.data.address);require 'net/http'
require 'json'
uri = URI('https://api.requiems.xyz/v1/places/reverse-geocode')
uri.query = URI.encode_www_form(lat: 38.8977, lon: -77.0365)
request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
data = JSON.parse(response.body)
puts data['data']['address']Error Responses
not_found
No address found for the given coordinates.
upstream_error
The geocoding service is temporarily unavailable.
bad_request
lat or lon is missing or out of range (lat: -90..90, lon: -180..180).
Frequently Asked Questions
The API uses Nominatim, the official geocoder for OpenStreetMap. It provides worldwide coverage and is kept up to date with OSM community edits.
Yes. Results are cached for 24 hours. Repeated calls with the same address or coordinates return instantly without hitting the upstream service.
Precision depends on the density of OpenStreetMap data at the given coordinates. In well-mapped areas (most cities worldwide) you will get street-level accuracy. Remote areas may return only a region or country.
Yes. Nominatim supports addresses in most languages and scripts. Pass the address in its native language for best results.