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

Descripción general

Casos de uso

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

Funcionalidades

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

Puntos finales de la API

Geocode Address

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

GET

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

Parámetros

Nombre	Tipo	Obligatorio	Descripción
address	`string`	Obligatorio	The address to geocode (street, city, country, or any combination)

Pruébalo

Demostración en vivo

Solicitud

address * (string)

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

Campos de respuesta

Campo	Tipo	Descripción
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

Ejemplos de código

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

Respuestas de error

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

Parámetros

Nombre	Tipo	Obligatorio	Descripción
lat	`number`	Obligatorio	Latitude of the location (-90 to 90)
lon	`number`	Obligatorio	Longitude of the location (-180 to 180)

Pruébalo

Demostración en vivo

Solicitud

lat * (number)

Latitude of the location (-90 to 90)

lon * (number)

Longitude of the location (-180 to 180)

Campos de respuesta

Campo	Tipo	Descripción
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)

Ejemplos de código

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

Respuestas de error

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

Parámetros

Nombre	Tipo	Obligatorio	Descripción
addresses	`array<string>`	Obligatorio	List of addresses to geocode (1–20 items, each non-empty). Max 20 due to Nominatim usage policy.

Pruébalo

Demostración en vivo

Solicitud

addresses * (array<string>)

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

Campos de respuesta

Campo	Tipo	Descripción
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.

Ejemplos de código

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

Respuestas de error

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

Parámetros

Nombre	Tipo	Obligatorio	Descripción
items	`array<object>`	Obligatorio	List of coordinate pairs to reverse-geocode (1–20 items). Max 20 due to Nominatim usage policy.
items[].lat	`number`	Obligatorio	Latitude (-90 to 90).
items[].lon	`number`	Obligatorio	Longitude (-180 to 180).

Pruébalo

Demostración en vivo

Solicitud

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

Campos de respuesta

Campo	Tipo	Descripción
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.

Ejemplos de código

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

Respuestas de error

validation_failed

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

bad_request

The request body is missing or malformed.

Geocoding

Descripción general

Casos de uso

Funcionalidades

Puntos finales de la API

Geocode Address

Parámetros

Pruébalo

Solicitud

Respuesta

Error

Campos de respuesta

Ejemplos de código

Respuestas de error

Reverse Geocode

Parámetros

Pruébalo

Solicitud

Respuesta

Error

Campos de respuesta

Ejemplos de código

Respuestas de error

Batch Geocode Addresses

Parámetros

Pruébalo

Solicitud

Respuesta

Error

Campos de respuesta

Ejemplos de código

Respuestas de error

Batch Reverse Geocode

Parámetros

Pruébalo

Solicitud

Respuesta

Error

Campos de respuesta

Ejemplos de código

Respuestas de error

Preguntas frecuentes