Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/V3RNE42/helios/llms.txt

Use this file to discover all available pages before exploring further.

The /api/geocode endpoint accepts a city name and country name and returns their geographic coordinates. It uses Nominatim (OpenStreetMap) as the primary geocoder, falling back to OpenCage when Nominatim fails or rate-limits.

​
Request

Method: GET
Path: /api/geocode
​
city
string
required
The city or locality name.
​
country
string
required
The country name.
curl "https://your-deployment.vercel.app/api/geocode?city=Madrid&country=Spain"

​
Response

On success the endpoint returns a JSON object with the coordinates of the requested city. 
{ "lat": 40.4168, "lon": -3.7038 }
​
lat
number
Latitude in decimal degrees.
​
lon
number
Longitude in decimal degrees.
On error, the endpoint returns a non-2xx HTTP status. The front-end detects this via response.ok and throws: 
No se pudieron obtener las coordenadas de "<city>, <country>" (<status>)
This error message is caught by the form submit handler and displayed to the user as an alert.

​
Providers

Primary — Nominatim (https://nominatim.openstreetmap.org/search)
No API key is required. The serverless function sends a valid User-Agent header as required by Nominatim’s usage policy. Fallback — OpenCage (https://api.opencagedata.com/geocode/v1/json)
Used when Nominatim fails or rate-limits. Requires the OPENCAGE_KEY environment variable.
City and country names are URL-encoded by the front-end using encodeURIComponent() before being passed as query parameters to this endpoint.

Build docs developers (and LLMs) love

Get started for freeTalk to us