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.

Helios needs exactly three environment variables, all of which are API keys for external services. They are never exposed to the browser — only the serverless functions in /api/ read them at request time on Vercel’s server-side runtime.

​
.env.example

The repository ships with a .env.example file at the project root that lists all required variables with empty values:
.env.example
# Copy to .env for local `vercel dev`, and set the same values as
# Environment Variables in the Vercel project dashboard for production.
# The previous keys were committed to git history and should be rotated.

# https://opencagedata.com/  — geocoding fallback (api/geocode.js)
OPENCAGE_KEY=

# https://ipgeolocation.io/  — timezone lookup (api/timezone.js)
IPGEOLOCATION_KEY=

# https://timezonedb.com/    — timezone fallback (api/timezone.js)
TIMEZONEDB_KEY=

​
Variable reference

​
OPENCAGE_KEY
string
required
OpenCage Data geocoding API key. Used by api/geocode.js as a fallback geocoder when the primary provider (Nominatim / OpenStreetMap) rate-limits or returns no results. Obtain a key at https://opencagedata.com/.
​
IPGEOLOCATION_KEY
string
required
ipgeolocation.io API key. The primary source for UTC-offset lookups in api/timezone.js. Given a latitude and longitude, the function calls ipgeolocation.io first and falls back to TimeZoneDB only if this call fails. Obtain a key at https://ipgeolocation.io/.
​
TIMEZONEDB_KEY
string
required
TimeZoneDB API key. The fallback timezone provider in api/timezone.js, used only when the ipgeolocation.io call fails. Obtain a key at https://timezonedb.com/.

​
Local development

For local development with vercel dev, copy the example file to .env at the project root and fill in your keys: 
cp .env.example .env
Then open .env and populate each variable:
.env
OPENCAGE_KEY=your_opencage_key_here
IPGEOLOCATION_KEY=your_ipgeolocation_key_here
TIMEZONEDB_KEY=your_timezonedb_key_here
vercel dev reads this file automatically and injects the variables into the serverless function runtime, exactly as production does. A plain static server such as python -m http.server does not serve the /api functions and therefore cannot use these variables.

​
Production (Vercel)

For production deployments, set the three variables in the Vercel dashboard under Settings → Environment Variables. They do not need to be committed to the repository — the Vercel runtime injects them into each serverless function invocation.
The previous API keys were committed to the repository’s git history. If you have forked or cloned this repository, you must rotate all three keys with their respective providers before deploying, as the old values are permanently visible in the commit log.
After adding or changing environment variables in the dashboard, trigger a new deployment for the changes to take effect.

​
How variables are consumed

Each serverless function reads only the keys it needs via process.env:
  • api/geocode.js — reads process.env.OPENCAGE_KEY inside the fromOpenCage function. The key is only accessed when Nominatim has already failed, so a missing key causes an error only in that fallback path.
  • api/timezone.js — reads process.env.IPGEOLOCATION_KEY inside fromIpGeolocation (called first) and process.env.TIMEZONEDB_KEY inside fromTimeZoneDB (called only if fromIpGeolocation throws). If either key is absent when its function is invoked, the function throws an explicit configuration error rather than making a malformed API request.
Neither function passes key values to the browser in any response — the keys remain server-side at all times.

Build docs developers (and LLMs) love

Get started for freeTalk to us