Uman Map Public API

Read-only REST access to the data published on the public Uman map: border crossing status, points of interest, routes, flights, zmanim and travel content.

GET /v1 returns a machine-readable index of every resource, so a client can discover the surface without reading this page.

Response shape

Every JSON response is an envelope with two keys. data is the payload; meta describes it.

{
  "data": { … },
  "meta": {
    "resource":     "borders",
    "generated_at": "2026-08-09T18:52:47+00:00",
    "age_seconds":  0,
    "ttl_seconds":  60,
    "stale":        false,
    "attribution":  [ { "name": "granica.gov.pl · CC BY 4.0", "url": null } ],
    "license":      "…"
  }
}

When the upstream source is briefly unreachable the last known good copy is served with meta.stale: true and a real age_seconds, rather than an error — a map being read at a border crossing is more useful slightly late than not at all. Check meta.stale if freshness matters to you.

Resources

Borders and geography

Places — search and proximity

These two share one filter set. Use /v1/nearby when you have a coordinate (a chat user sharing their location, say) and /v1/places when you have words. Both search all 15 layers at once — about 685 points.

Each result carries name, name_en, address, city, lat, lng, its layer with the layer's Hebrew layer_name, icon and category, an attrs object (phone, hours, kashrut, website, subtype where the operator supplied them), and a ready maps_url.

Layers and overlays

Layers split across two scopes: the wider region (mikvah, tombs, kosher_food, gas, bus_parking, emergency, layer) and Uman city itself (hotels, uman_shuls, uman_mikvahs, uman_kosher, uman_grocery, uman_atm, uman_banks, uman_medical). Search endpoints cover both by default. Read /v1/layers rather than hard-coding this list.

Some points appear in both a regional and an Uman layer — the same mikvah can be listed twice with different ids. Deduplicate on coordinates if that matters to you.

Travel and time

Content

Payload sizes

Route geometry is roughly 98% of the total data. /v1/bundle therefore omits it unless you ask:

Send Accept-Encoding: gzip. Prefer a single /v1/bundle over fifteen catalogue calls.

Caching

Responses carry ETag and Cache-Control. Send the ETag back as If-None-Match to get 304 Not Modified and no body. X-Cache reports HIT or MISS.

Border status has a 60-second TTL; catalogues 5 minutes; geometry and the eruv PDF far longer. Polling faster than the TTL only spends your rate limit — it cannot return fresher data.

For change detection, /v1/bundle exposes poll_version: an opaque digest that changes when the underlying data changes. Compare it, do not parse it.

Errors

{ "error": "bad_param", "detail": "Invalid value for 'lat'." }

Examples

# Discover the surface
curl https://api-pub.umanmap.eu/v1

# Border status, compressed
curl -H 'Accept-Encoding: gzip' --compressed \
     https://api-pub.umanmap.eu/v1/borders

# A chat user shared their location — what is within 1 km?
curl 'https://api-pub.umanmap.eu/v1/nearby?lat=48.7519&lng=30.2158&radius=1000&limit=8'

# Kosher food near them, only entries that list a phone number
curl 'https://api-pub.umanmap.eu/v1/nearby?lat=48.7519&lng=30.2158&category=food&has=phone'

# Nearest synagogues, two specific layers
curl 'https://api-pub.umanmap.eu/v1/nearby?lat=48.7519&lng=30.2158&layers=uman_shuls,mikvah&limit=5'

# Text search, no location needed
curl 'https://api-pub.umanmap.eu/v1/places?q=hotel&limit=10'

# What can I filter by?
curl https://api-pub.umanmap.eu/v1/layers

# Zmanim for Uman today
curl 'https://api-pub.umanmap.eu/v1/zmanim?lat=48.75&lng=30.22'

# Everything except geometry, in one call
curl 'https://api-pub.umanmap.eu/v1/bundle?scope=uman'

# The eruv map (PDF)
curl -o eruv.pdf https://api-pub.umanmap.eu/v1/eruv

Notes and limits

• Read-only by design. Border and problem reports are submitted through the map itself, not here.
• Geocoding, place lookup and route calculation are deliberately not exposed — they are metered third-party services.
• No personal data is served: no user accounts, no reporter identities, no contact records beyond the published hotline list, no vehicle tracking.
• /v1 is stable. Breaking changes will appear under a new version prefix.