Helios integrates with three external APIs to resolve city names to coordinates and to determine the UTC offset at the departure point. All three offer free tiers that are sufficient for development and light production use.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.
Nominatim (OpenStreetMap) is the primary geocoder and requires no API key.
api/geocode.js calls Nominatim first, supplying a proper User-Agent header as required by Nominatim’s usage policy. OpenCage is only contacted when Nominatim fails or returns no results.OpenCage Data (OPENCAGE_KEY)
What it does in Helios
api/geocode.js translates a city + country pair into a { lat, lon } coordinate pair. Nominatim is tried first at no cost. If Nominatim rate-limits the request or returns an empty result set, the function automatically retries with OpenCage Data as the fallback geocoder.
How to obtain a key
Create an account
Go to https://opencagedata.com/ and sign up for a free account.
| Detail | Value |
|---|---|
| Environment variable | OPENCAGE_KEY |
| Role | Geocoding fallback (after Nominatim) |
| Free tier | 2,500 requests / day |
| Sign-up URL | https://opencagedata.com/ |
ipgeolocation.io (IPGEOLOCATION_KEY)
What it does in Helios
api/timezone.js accepts a latitude and longitude and returns the UTC offset in hours as { offset }. ipgeolocation.io is the primary provider for this lookup. The function calls it first on every request and only falls back to TimeZoneDB if this call fails.
How to obtain a key
Create an account
Go to https://ipgeolocation.io/ and sign up for a free account.
| Detail | Value |
|---|---|
| Environment variable | IPGEOLOCATION_KEY |
| Role | Timezone lookup — primary provider |
| Free tier | 30,000 requests / month |
| Sign-up URL | https://ipgeolocation.io/ |
TimeZoneDB (TIMEZONEDB_KEY)
What it does in Helios
TimeZoneDB is the fallback timezone provider inapi/timezone.js. It is only contacted when the ipgeolocation.io call fails (for example, due to a quota limit or a service outage). It accepts a latitude and longitude and returns the GMT offset in seconds, which the function converts to hours before responding.
How to obtain a key
Create an account
Go to https://timezonedb.com/ and register for a free account.
| Detail | Value |
|---|---|
| Environment variable | TIMEZONEDB_KEY |
| Role | Timezone lookup — fallback provider |
| Free tier | Available |
| Sign-up URL | https://timezonedb.com/ |
Summary
| Service | Variable | Role | Free tier |
|---|---|---|---|
| Nominatim (OpenStreetMap) | (none required) | Geocoding — primary | Unlimited* |
| OpenCage Data | OPENCAGE_KEY | Geocoding — fallback | 2,500 req/day |
| ipgeolocation.io | IPGEOLOCATION_KEY | Timezone lookup — primary | 30,000 req/month |
| TimeZoneDB | TIMEZONEDB_KEY | Timezone lookup — fallback | Available |
api/geocode.js complies by sending a descriptive User-Agent header on every request.
Once you have all three keys, follow the Environment Variables guide to put them in the right place for local development or production.