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

Vue d'ensemble

Cas d'utilisation

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

Fonctionnalités

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

Points de terminaison de l'API

Geocode Address

Converts a free-text address into latitude and longitude coordinates.

GET

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

Paramètres

Nom	Type	Requis	Description
address	`string`	Requis	The address to geocode (street, city, country, or any combination)

Essayez-le

Démo en direct

Requête

address * (string)

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

Champs de réponse

Champ	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

Exemples de code

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']}"

Réponses d'erreur

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

Paramètres

Nom	Type	Requis	Description
lat	`number`	Requis	Latitude of the location (-90 to 90)
lon	`number`	Requis	Longitude of the location (-180 to 180)

Essayez-le

Démo en direct

Requête

lat * (number)

Latitude of the location (-90 to 90)

lon * (number)

Longitude of the location (-180 to 180)

Champs de réponse

Champ	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)

Exemples de code

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']

Réponses d'erreur

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

Paramètres

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

Essayez-le

Démo en direct

Requête

addresses * (array<string>)

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

Champs de réponse

Champ	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.

Exemples de code

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

Réponses d'erreur

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

Paramètres

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

Essayez-le

Démo en direct

Requête

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).

Champs de réponse

Champ	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.

Exemples de code

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

Réponses d'erreur

validation_failed

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

bad_request

The request body is missing or malformed.

Geocoding

Vue d'ensemble

Cas d'utilisation

Fonctionnalités

Points de terminaison de l'API

Geocode Address

Paramètres

Essayez-le

Requête

Réponse

Erreur

Champs de réponse

Exemples de code

Réponses d'erreur

Reverse Geocode

Paramètres

Essayez-le

Requête

Réponse

Erreur

Champs de réponse

Exemples de code

Réponses d'erreur

Batch Geocode Addresses

Paramètres

Essayez-le

Requête

Réponse

Erreur

Champs de réponse

Exemples de code

Réponses d'erreur

Batch Reverse Geocode

Paramètres

Essayez-le

Requête

Réponse

Erreur

Champs de réponse

Exemples de code

Réponses d'erreur

Foire aux questions