# orbit Geo & Time

> Location and time data for agents: weather now + 7-day forecast (MET Norway), geocoding and reverse geocoding (OpenStreetMap Nominatim), sunrise/sunset, world time-zone conversion and public holidays (Nager.Date). Real open data fetched at call time, attribution included. $0.001 per call. Pay per call with x402 (USDC on Base, no account, no API key). Free MCP (trimmed sample output) at https://orbit-geo.orbit-builder.workers.dev/mcp. By orbit-builder.

## Paid endpoints (x402 v2, exact, eip155:8453, USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913, payTo 0x9Da4B249B8afa7818de5BFf7eEd8b13e6feeb9b3). Bad input is rejected with 400 before payment; upstream errors return >=400 and are never settled. A call with no parameters runs the example input shown.

- Weather now + 7-day forecast ($0.001): GET or POST https://orbit-geo.orbit-builder.workers.dev/v1/weather — Weather for any point on Earth from MET Norway (Norwegian Meteorological Institute): current temperature °C, wind m/s + direction, humidity, cloud %, pressure, condition, next-hour precipitation; next 24 hourly steps; daily min/max temp, total precip and dominant condition for ~7 days. Give lat+lon or a place name (geocoded via OpenStreetMap).
  params: lat (latitude); lon (longitude); place (or a place name, e.g. Almaty or Paris, France); hours (hourly steps to include (1-48, default 24))
  example: https://orbit-geo.orbit-builder.workers.dev/v1/weather?place=Almaty&hours=6
- Geocode a place or address ($0.001): GET or POST https://orbit-geo.orbit-builder.workers.dev/v1/geocode — Forward geocoding from OpenStreetMap (Nominatim): turn a place name or address into up to 5 matches with lat/lon, full display name, type/class, importance, bounding box, and structured address (road, city, state, postcode, country, country_code). Attribution © OpenStreetMap contributors (ODbL). No match returns 404 (not charged).
  params: q* (place name or address); limit (1-5 (default 3))
  example: https://orbit-geo.orbit-builder.workers.dev/v1/geocode?q=Eiffel+Tower%2C+Paris&limit=1
- Reverse geocode coordinates ($0.001): GET or POST https://orbit-geo.orbit-builder.workers.dev/v1/reverse — Reverse geocoding from OpenStreetMap (Nominatim): turn lat/lon into the nearest address: display name, house number, road, suburb, city, county, state, postcode, country, ISO country code, OSM id. Attribution © OpenStreetMap contributors (ODbL). Ocean/unmapped point returns 404 (not charged).
  params: lat* (latitude); lon* (longitude); zoom (detail 3 (country) … 18 (building), default 18)
  example: https://orbit-geo.orbit-builder.workers.dev/v1/reverse?lat=40.7484&lon=-73.9857
- Sunrise, sunset, twilight ($0.001): GET or POST https://orbit-geo.orbit-builder.workers.dev/v1/sun — Sunrise, sunset, solar noon (with sun elevation) and day length for any point and date, from MET Norway's Sunrise 3.0 API, in the requested UTC offset. Give lat+lon or place name; date defaults to today. Polar day/night returns null times with a note.
  params: lat (latitude); lon (longitude); place (or a place name, e.g. Almaty or Paris, France); date (YYYY-MM-DD (default today UTC)); offset (UTC offset for output, e.g. +05:00 (default +00:00))
  example: https://orbit-geo.orbit-builder.workers.dev/v1/sun?place=Reykjavik&offset=%2B00%3A00
- World time & time-zone conversion ($0.001): GET or POST https://orbit-geo.orbit-builder.workers.dev/v1/time — Current local time, weekday, UTC offset and DST flag for up to 10 IANA time zones (e.g. Asia/Almaty, America/New_York), and optional conversion of a given local time from one zone into all of them. Computed from the IANA tz database at call time.
  params: zones (comma-separated IANA zones (default UTC,America/New_York,Europe/London,Asia/Tokyo)); time (optional time to convert: YYYY-MM-DDTHH:MM local to from_tz, or ISO with Z/offset); from_tz (zone of 'time' (default UTC))
  example: https://orbit-geo.orbit-builder.workers.dev/v1/time?zones=Asia%2FAlmaty%2CAmerica%2FNew_York%2CEurope%2FBerlin&time=2026-12-31T23%3A00&from_tz=Asia%2FAlmaty
- Public holidays by country ($0.001): GET or POST https://orbit-geo.orbit-builder.workers.dev/v1/holidays — Official public holidays for 100+ countries from Nager.Date: for a country (ISO alpha-2) and year, every holiday with date, local and English name, nationwide vs regional (counties), type (Public, Bank, School…). Also flags whether a given date is a holiday and lists the next upcoming ones. Unsupported country returns 404 (not charged).
  params: country* (ISO 3166-1 alpha-2, e.g. US, DE, KZ); year (default current year); date (optional YYYY-MM-DD to test)
  example: https://orbit-geo.orbit-builder.workers.dev/v1/holidays?country=KZ&year=2026

Bad input returns 400 before payment; not-found and upstream errors return 4xx/5xx and are never settled.

## Free

- https://orbit-geo.orbit-builder.workers.dev/v1/preview?tool=<name> (runs the fixed example input live)
- MCP (streamable HTTP, JSON-RPC 2.0 POST): https://orbit-geo.orbit-builder.workers.dev/mcp — tools: weather_forecast, geocode, reverse_geocode, sun_times, world_time, public_holidays
- https://orbit-geo.orbit-builder.workers.dev/openapi.json, https://orbit-geo.orbit-builder.workers.dev/.well-known/x402, https://orbit-geo.orbit-builder.workers.dev/.well-known/agent.json

## Data sources
- weather_forecast: MET Norway Locationforecast/Sunrise, CC BY 4.0 (api.met.no); place names © OpenStreetMap contributors, ODbL (data via Nominatim)
- geocode: © OpenStreetMap contributors, ODbL (data via Nominatim)
- reverse_geocode: © OpenStreetMap contributors, ODbL (data via Nominatim)
- sun_times: MET Norway Locationforecast/Sunrise, CC BY 4.0 (api.met.no); place names © OpenStreetMap contributors, ODbL (data via Nominatim)
- world_time: IANA time zone database (Intl API) at call time
- public_holidays: Nager.Date public holiday API (date.nager.at, MIT)