Internal mapping platform · Iran scope

Build location features on one stable map contract.

JaserMap provides normalized search, reverse geocoding, vector tiles, raster tiles, and a Map.ir-compatible facade for existing company services. This documentation is for consumers of JaserMap — not for deploying JaserMap itself.

Test the API live Integrate in 60 seconds

HTTPSServer-side API keysfa · en · arOSM / OpenMapTilesMap.ir migration path

Your serviceFood · Taxi · Web · Backend

x-api-key

Single entry pointmap.jaserlink.com

SearchGateway

ReversePhoton

VectorMartin

RasterRenderer

Base URLhttps://map.jaserlink.com

CoverageIran

Languagesfa · en · ar

Coordinate systemWGS84

Quick Start

Your first authenticated request

Use the project key assigned to your service. Send it in the x-api-key header. Keep long-lived keys on your backend; do not hard-code them into public browser JavaScript.

Search near a user

curl --get 'https://map.jaserlink.com/api/v1/search' \
  -H 'x-api-key: YOUR_PROJECT_KEY' \
  --data-urlencode 'q=Azadi Square Tehran' \
  --data 'lang=en' \
  --data 'lat=35.6997' \
  --data 'lon=51.3375' \
  --data 'limit=5'

200 · application/json

{
  "items": [
    {
      "name": "Azadi Square",
      "display_address": "…",
      "lat": 35.6997,
      "lon": 51.3375,
      "type": "…",
      "city": "Tehran",
      "state": "Tehran",
      "country": "Iran"
    }
  ]
}

Recommended

For autocomplete and forward search, send the user's current GPS location or current map center as lat and lon. Proximity bias materially improves relevance for incomplete place names.

Authentication

Project-scoped API keys

Header

Protected endpoints require x-api-key: <project key>. Missing or invalid keys return 401.

Keep it server-side

Use backend-to-backend calls or your own service proxy. Do not embed long-lived keys in public web bundles.

Independent consumers

Use a dedicated key per service where practical, so access can be rotated or revoked without affecting other integrations.

x-api-key→map.jaserlink.com→authenticated API / tiles

API Reference

Native HTTP API

The native API is the preferred contract for new integrations. It hides Photon and tile-server implementation details behind JaserMap.

Returns Gateway health and its current Photon dependency state. Use this for diagnostics, not as a substitute for your own request-level error handling.

AuthenticationNone

Success200

Degraded503

{
  "status": "ok",
  "dependencies": { "photon": { "ok": true } }
}

Searches indexed OSM data and returns normalized places. Supplying both lat and lon enables proximity bias.

ParameterTypeRequiredDescription

qstringYesSearch text.

langfa | en | arNoResponse language preference. Default: fa.

latnumberNo*Latitude for proximity bias. Must be supplied together with lon.

lonnumberNo*Longitude for proximity bias. Must be supplied together with lat.

limitintegerNoClamped to 1–50. Default: 10.

Returns the best nearby normalized feature for a coordinate. JaserMap asks the geocoder for multiple nearby candidates and applies a stable preference toward house/POI, street, locality, then city-level results.

ParameterTypeRequiredDescription

lat-90…90YesWGS84 latitude.

lon-180…180YesWGS84 longitude.

langfa | en | arNoResponse language preference. Default: fa.

Normalized model

Place

Stable native shape

idProvider-derived stable-ish identifier when available.

nameBest short display name.

display_addressHuman-readable normalized address.

compact_addressShorter address when available.

lat / lonWGS84 decimal coordinates.

typeUnderlying feature classification.

house_numberHouse number when present in source data.

streetRoad or street label.

neighborhood / districtLocal administrative context when available.

city / county / stateAdministrative hierarchy when available.

countryCountry label from source data.

postcodePostal code when available in OSM data.

Tiles

Vector and raster delivery

API key

Native vector tiles

Use the iran TileJSON source for MapLibre or another vector-tile client.

GET /tiles/iran GET /tiles/iran/{z}/{x}/{y}

Best for interactive styling and high-DPI rendering.
Data includes localized names where OSM provides them.
Do not put a long-lived API key directly in a public browser bundle; proxy through your service when needed.

API key

Native raster XYZ

Use this endpoint with Leaflet/OpenLayers integrations that expect PNG XYZ tiles.

GET /tiles/raster/{z}/{x}/{y}.png

Rendered from the JaserMap/OpenMapTiles data stack.
Responses are cache-friendly.
Use attribution: © OpenMapTiles © OpenStreetMap contributors.

Coordinate convention

Normal API parameters use lat, lon. GeoJSON coordinate arrays use [longitude, latitude]. XYZ tiles use standard Web Mercator slippy-map coordinates.

Compatibility

Map.ir migration surface

Existing services can migrate incrementally. The compatibility facade intentionally mirrors only the Map.ir shapes that current company integrations need. It is not a claim of complete Map.ir API parity.

Beforemap.ir

→

Aftermap.jaserlink.com

Keep x-api-key, replace the upstream URL and key.

Used by the current Food delivery-map integration. Required Food fields are frozen: address, postal_address, address_compact, city, province, and neighborhood.

Accepts {"text":"…","location":{"type":"Point","coordinates":[lon,lat]}}. The response uses odata.count and value. No current Food flow depends on this contract, so it should not be treated as frozen yet.

Currently handled by the same compatibility search implementation as /search. Treat it as provisional until a real consumer contract is inventoried and frozen.

This path exists so current Leaflet-based Food code can keep its existing URL template and switch only hostname + API key. The rendered visual style is JaserMap/OpenMapTiles, not Map.ir's proprietary cartography.

Live API Lab

Call production endpoints from this page

The lab sends same-origin requests directly to map.jaserlink.com. Your API key remains only in this page's input field and is not written to localStorage or cookies. It will still be visible in your browser's own Network panel, as expected for any request header.

Project API key

Required for protected API and tile tests. Health is public.

Live serviceChecking…

Request preview

Select a lab and run a request.

Visual resultAzadi Square, Tehran

z15

Map preview

◌Run an endpoint

Structured results and visual previews will appear here.

Raw response

Waiting

{
  "message": "Run a live request to inspect the response."
}

Integration Recipes

Patterns for company services

Laravel / server-side HTTP

Keep the project key in your service environment and call JaserMap from the backend.

Set short connection/read timeouts appropriate to your request path.
Retry only transient failures.
Pass user/map coordinates to search for better relevance.

Laravel example

$response = Http::withHeaders([
    'x-api-key' => config('services.jasermap.key'),
])->timeout(8)->get('https://map.jaserlink.com/api/v1/search', [
    'q' => 'Azadi Square Tehran',
    'lang' => 'en',
    'lat' => 35.6997,
    'lon' => 51.3375,
    'limit' => 5,
]);

$places = $response->throw()->json('items');

Python / requests

Use the native API contract for new backend integrations.

Python example

import requests

response = requests.get(
    "https://map.jaserlink.com/api/v1/reverse",
    headers={"x-api-key": JASERMAP_API_KEY},
    params={"lat": 35.6997, "lon": 51.3375, "lang": "en"},
    timeout=8,
)
response.raise_for_status()
place = response.json()

Leaflet / raster consumer

For a public browser application, do not expose the long-lived JaserMap project key. Proxy the tile route through your own backend, then point Leaflet at that same-origin route.

Browser-side Leaflet

const map = L.map('map').setView([35.6997, 51.3375], 13);

L.tileLayer('/map/tiles/{z}/{x}/{y}.png', {
  maxZoom: 22,
  attribution: '© OpenMapTiles © OpenStreetMap contributors',
}).addTo(map);

// Your backend route calls:
// GET https://map.jaserlink.com/tiles/raster/{z}/{x}/{y}.png
// with x-api-key server-side.

Food — drop-in Map.ir migration

The current Food delivery map can keep its Leaflet code and server-side proxy/cache layer. Change the key, two upstream URLs, and attribution.

Food environment values

FOOD_DELIVERY_MAP_PROVIDER=mapir
FOOD_DELIVERY_MAP_TILE_URL=/map/tiles/{z}/{x}/{y}.png
FOOD_DELIVERY_MAP_ATTRIBUTION="© OpenMapTiles © OpenStreetMap contributors"

FOOD_DELIVERY_MAPIR_API_KEY=<food-specific-jasermap-key>
FOOD_DELIVERY_MAPIR_TILE_URL=https://map.jaserlink.com/shiveh/xyz/1.0.0/Shiveh:Shiveh@EPSG:3857@png/{z}/{x}/{y}.png
FOOD_DELIVERY_MAPIR_REVERSE_URL=https://map.jaserlink.com/reverse/

Errors & Resilience

Design consumers for failure

400Invalid or missing request parameters.{"error":"invalid_lat_lon"}

401Missing or invalid project API key.{"error":"invalid_api_key"}

404No reverse result was found for the coordinate.{"error":"not_found"}

429Public demo traffic exceeded its Nginx rate limit. Demo limits are not the authenticated service contract.

502Geocoding upstream failed or returned an invalid response.

503Health dependency is degraded.

Timeout

Set a finite client timeout. Existing Food uses 8 seconds.

Retry selectively

Retry transient network/5xx errors with a small bounded count. Avoid retry storms.

Cache responsibly

Raster tiles are highly cacheable. Reverse/search caching should account for coordinates and language.

Fallback UX

Location pickers should keep selected coordinates even when address lookup temporarily fails.

Contract Notes

What consumers should know

Iran-only data scope

The current production data artifact covers Iran. Do not assume equivalent coverage outside Iran.

Language is data-dependent

The platform supports fa, en, and ar, but a particular OSM feature may not have every localized name. Fallback labels can therefore occur.

Address wording can differ

JaserMap reverse geocoding is normalized from OSM/Photon data. Human-readable address text is not guaranteed to be byte-for-byte identical to Map.ir.

Compatibility is scoped

Food reverse + Shiveh raster behavior is the validated legacy subset. Compatibility search remains provisional.

Tile style is JaserMap

The compatibility raster URL shape does not reproduce Map.ir's proprietary visual style; it serves JaserMap's own rendered map.

No routing/traffic contract

The current service provides mapping, tiles, search, autocomplete and reverse geocoding. Routing, matrix, navigation and live traffic are not part of this contract.

Consumer Checklist

Before you ship an integration

Use a service-specific API keyKeep it out of browser source and public logs. Use the native API for new integrationsPrefer /api/v1/* unless you are migrating legacy Map.ir code. Send proximity coordinates for searchUse GPS or current map center when available. Choose a language explicitlyUse fa, en or ar when the client experience depends on it. Handle 4xx/5xx without losing user inputCoordinates should remain usable even when geocoding is temporarily unavailable. Cache tilesRespect cache headers and avoid unnecessary re-fetches. Use correct attribution© OpenMapTiles © OpenStreetMap contributors. Test on real target coordinatesValidate the cities and user flows your service actually serves.