Geocoding

Convert human-readable addresses into geographic coordinates (geocoding) and convert coordinates back into addresses (reverse geocoding). Powered by OpenStreetMap via the Nominatim API.

Get API Key

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://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 Demo

Request

address * (string)

The address to geocode (street, city, country, or any combination)

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://requiems.xyz/v1/places/geocode?address=1600+Pennsylvania+Ave+NW" \
  -H "requiems-api-key: YOUR_API_KEY"

import requests

url = "https://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://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://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://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 Demo

Request

lat * (number)

Latitude of the location (-90 to 90)

lon * (number)

Longitude of the location (-180 to 180)

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://requiems.xyz/v1/places/reverse-geocode?lat=38.8977&lon=-77.0365" \
  -H "requiems-api-key: YOUR_API_KEY"

import requests

url = "https://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://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://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).

Batch Geocode Addresses

Convert up to 20 addresses to coordinates in a single request. Processed concurrently; results are returned in input order. Per-item errors are reported inline. Cache hits avoid outbound network calls.

POST

https://requiems.xyz/v1/places/geocode/batch

Parameters

Name	Type	Required	Description
addresses	`array<string>`	Required	List of addresses to geocode (1–20 items, each non-empty). Max 20 due to Nominatim usage policy.

Try it out

Live Demo

Request

addresses * (array<string>)

List of addresses to geocode (1–20 items, each non-empty). Max 20 due to Nominatim usage policy.

Response Fields

Field	Type	Description
results	`array<object>`	Per-item results in input order.
results[].address	`string`	The original address as provided in the request.
results[].result	`object`	Geocoding result (omitted on error). Same fields as the single-item endpoint.
results[].error	`string`	Error message if geocoding failed (omitted on success).
total	`integer`	Total number of items processed.

Code Examples

curl -X POST https://requiems.xyz/v1/places/geocode/batch \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"addresses": ["1600 Pennsylvania Ave NW, Washington DC", "Eiffel Tower, Paris"]}'

import requests

url = "https://requiems.xyz/v1/places/geocode/batch"
headers = {
    "requiems-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {"addresses": ["1600 Pennsylvania Ave NW, Washington DC", "Eiffel Tower, Paris"]}

response = requests.post(url, headers=headers, json=payload)
for item in response.json()["data"]["results"]:
    if item.get("result"):
        print(item["result"]["lat"], item["result"]["lon"])

const response = await fetch('https://requiems.xyz/v1/places/geocode/batch', {
  method: 'POST',
  headers: {
    'requiems-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    addresses: ['1600 Pennsylvania Ave NW, Washington DC', 'Eiffel Tower, Paris']
  })
});

const { data } = await response.json();
data.results.forEach(item => {
  if (item.result) console.log(item.result.lat, item.result.lon);
});

require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/places/geocode/batch')
request = Net::HTTP::Post.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = {
  addresses: ['1600 Pennsylvania Ave NW, Washington DC', 'Eiffel Tower, Paris']
}.to_json

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)['data']
data['results'].each do |item|
  puts "#{item['result']['lat']}, #{item['result']['lon']}" if item['result']
end

Error Responses

validation_failed

The addresses array is missing, empty, or exceeds 20 items.

bad_request

The request body is missing or malformed.

Batch Reverse Geocode

Convert up to 20 coordinate pairs to addresses in a single request. Processed concurrently; results are returned in input order. Per-item errors are reported inline.

POST

https://requiems.xyz/v1/places/reverse-geocode/batch

Parameters

Name	Type	Required	Description
items	`array<object>`	Required	List of coordinate pairs to reverse-geocode (1–20 items). Max 20 due to Nominatim usage policy.
items[].lat	`number`	Required	Latitude (-90 to 90).
items[].lon	`number`	Required	Longitude (-180 to 180).

Try it out

Live Demo

Request

items * (array<object>)

List of coordinate pairs to reverse-geocode (1–20 items). Max 20 due to Nominatim usage policy.

items[].lat * (number)

Latitude (-90 to 90).

items[].lon * (number)

Longitude (-180 to 180).

Response Fields

Field	Type	Description
results	`array<object>`	Per-item results in input order.
results[].lat	`number`	Latitude as provided in the request.
results[].lon	`number`	Longitude as provided in the request.
results[].result	`object`	Reverse geocoding result (omitted on error). Same fields as the single-item endpoint.
results[].error	`string`	Error message if reverse geocoding failed (omitted on success).
total	`integer`	Total number of items processed.

Code Examples

curl -X POST https://requiems.xyz/v1/places/reverse-geocode/batch \
  -H "requiems-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items": [{"lat": 38.8977, "lon": -77.0365}, {"lat": 48.8584, "lon": 2.2945}]}'

import requests

url = "https://requiems.xyz/v1/places/reverse-geocode/batch"
headers = {
    "requiems-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "items": [
        {"lat": 38.8977, "lon": -77.0365},
        {"lat": 48.8584, "lon": 2.2945}
    ]
}

response = requests.post(url, headers=headers, json=payload)
for item in response.json()["data"]["results"]:
    if item.get("result"):
        print(item["result"]["address"])

const response = await fetch('https://requiems.xyz/v1/places/reverse-geocode/batch', {
  method: 'POST',
  headers: {
    'requiems-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    items: [
      { lat: 38.8977, lon: -77.0365 },
      { lat: 48.8584, lon: 2.2945 }
    ]
  })
});

const { data } = await response.json();
data.results.forEach(item => {
  if (item.result) console.log(item.result.address);
});

require 'net/http'
require 'json'

uri = URI('https://requiems.xyz/v1/places/reverse-geocode/batch')
request = Net::HTTP::Post.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = {
  items: [
    { lat: 38.8977, lon: -77.0365 },
    { lat: 48.8584, lon: 2.2945 }
  ]
}.to_json

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)['data']
data['results'].each do |item|
  puts item['result']['address'] if item['result']
end

Error Responses

validation_failed

The items array is missing, empty, or exceeds 20 items.

bad_request

The request body is missing or malformed.

Geocoding

Overview

Use Cases

Features

API Endpoints

Geocode Address

Parameters

Try it out

Request

Response

Error

Response Fields

Code Examples

Error Responses

Reverse Geocode

Parameters

Try it out

Request

Response

Error

Response Fields

Code Examples

Error Responses

Batch Geocode Addresses

Parameters

Try it out

Request

Response

Error

Response Fields

Code Examples

Error Responses

Batch Reverse Geocode

Parameters

Try it out

Request

Response

Error

Response Fields

Code Examples

Error Responses

Frequently Asked Questions