Endpoints

Map style

GET/style.json

A complete MapLibre style over the Orvia tiles. Point any MapLibre SDK at it. Not counted toward your usage units — the tiles the map then loads are (1 unit each).

Vector tiles

GET/tiles/{z}/{x}/{y}.pbf

Mapbox Vector Tiles, 512 px, zoom 0–14 (MapLibre overzooms beyond). Source layers: landuse, water, waterways, buildings, boundaries, roads, roads_small, railways, and from zoom 13 pois (points with category and name).

Search

GET/search?q=…&limit=…

Places whose name matches, best first (exact, then prefix, then by importance). Arabic ي/ك match ی/ک.

{"query":"شیراز","count":2,"results":[
  {"id":26082452,"name":"شیراز","type":"city","population":1565572,"lat":29.6060218,"lon":52.5378041},
  {"id":1999068394,"name":"شیراز","type":"village","population":null,"lat":37.4352186,"lon":45.909407}]}

Geocoding

GET/geocode?q=…

The single best match for a place name, with its coordinates. 404 when nothing matches.

{"query":"اصفهان","result":{"id":26038567,"name":"اصفهان","type":"city","population":1961260,"lat":32.6707877,"lon":51.6650002}}

Reverse geocoding

GET/reverse?lat=…&lon=…

The nearest named place to a point, and how far it is.

{"lat":35.6997,"lon":51.338,"result":{"id":5637867019,"name":"استاد معین","type":"neighbourhood",
  "population":null,"lat":35.6965676,"lon":51.3424727,"distanceKm":0.53}}

Routing

GET/route?from=lat,lon&to=lat,lon

The fastest driving route. Both ends are snapped to the nearest drivable road (within ~10 km); oneway streets and access restrictions are respected. Distance is in meters, duration in seconds, and the line is GeoJSON ([lon, lat] pairs).

{"route":{
  "distanceM":4755,"durationS":291,
  "from":{"lat":35.6997,"lon":51.338,"snappedTo":{"lat":35.698751,"lon":51.338088},"snapDistanceM":106},
  "to":{"lat":35.7219,"lon":51.3347,"snappedTo":{"lat":35.72193,"lon":51.334708},"snapDistanceM":3},
  "roads":[{"name":"بزرگراه محمدعلی جناح (57)","distanceM":2257},{"name":"بلوار آیت الله کاشانی (164)","distanceM":1809}],
  "geometry":{"type":"LineString","coordinates":[[51.338088,35.698751],[51.338531,35.698778], …]}}}

Weather

Observations and 3-day forecasts from the Iran Meteorological Organization (IRIMO) — about 430 stations, refreshed every 30 minutes. Conditions are one of clear, partly_cloudy, cloudy, showers, rain, storm, snow, fog, dust (or unknown where a station publishes readings only), with IRIMO's own Persian wording in text. The station list costs 2 units; a station's detail with its forecast, or the nearest station to a point, 3.

GET /api/v1/weather/stations[?bbox=…]   → every station: temperature, humidity, wind, condition
GET /api/v1/weather/{station}            → current weather in detail + 3-day forecast
GET /api/v1/weather?lat=35.70&lon=51.39  → the same for the nearest station

{ "id": "17550", "name": "بجنورد",
  "current": { "temperatureC": 10, "humidity": 87, "windKmh": 14, "windDirection": "غربی",
               "condition": { "kind": "rain", "windy": false, "daylight": "night", "text": "بارش باران" },
               "max24hC": 19, "min24hC": 9, "visibility": "9000متر", … },
  "forecast": [ { "label": "24 ساعت اول", "minC": 6, "maxC": 18,
                  "condition": { "kind": "partly_cloudy", "text": "قسمتی ابری تا ابری همراه با غبارصبحگاهی", … } }, … ],
  "source": { "name": "Iran Meteorological Organization (IRIMO)", "url": "https://www.irimo.ir/…" } }

Air quality

The hourly air quality index (AQI) from the Department of Environment's monitoring network — about 150 regions, refreshed every 30 minutes. Each region has its aqi, a level (good, moderate, sensitive, unhealthy, very_unhealthy, hazardous — the US EPA bands), the pollutant that sets it and the sub-index of each pollutant (null where there is no sensor). 2 units per call.

GET /api/v1/air/regions                → every region
GET /api/v1/air?lat=35.70&lon=51.39     → the nearest region

{ "name": "تهران", "province": "تهران", "aqi": 91, "level": "moderate", "pollutant": "PM2.5",
  "pollutants": { "pm25": 91, "pm10": 63, "o3": 33, "no2": 75, "so2": 29, "co": 25 },
  "observedAt": "1405/08/05 11:00", "distanceKm": 0.4,
  "source": "Department of Environment (aqms.doe.ir)" }

Elevation

Metres above sea level for any point — or up to 100 points in one call, e.g. for an elevation profile along a route. From the SRTM / GMTED / ETOPO1 terrain models (AWS Terrain Tiles), interpolated between ~38 m samples. 1 unit per 25 points (or part of them).

GET /api/v1/elevation?lat=35.955&lon=52.110
GET /api/v1/elevation?points=35.70,51.34|35.955,52.110

{ "results": [ { "lat": 35.955, "lon": 52.11, "elevationM": 5597.4 } ],
  "source": "AWS Terrain Tiles (SRTM, GMTED, ETOPO1)" }

Nearby places

GET/nearby?lat=…&lon=…&category=…&radius=…&limit=…

Points of interest closest to a point, nearest first — fuel stations, pharmacies, hospitals, banks and more, with opening hours and phone numbers where known.

{"lat":35.6997,"lon":51.338,"radius":2000,"count":1,"results":[
  {"id":"way/384953204","category":"fuel","name":"پمپ بنزین و گازوئیل","lat":35.6993983,"lon":51.3421838,
   "details":{"opening_hours":"24/7","addr:street":"خیابان آزادی"},"distanceM":379}]}

Places in an area

GET/pois?bbox=minLon,minLat,maxLon,maxLat&category=…&limit=…

Points of interest inside a bounding box (at most 0.5° across), named ones first. Same result shape as nearby, without distanceM. limit 1–1000, default 200.