API Sənədləri

Azərbaycanın yer datası — 66 rayon, 4248 kənd, 17283 küçə, 61813 obyekt — koordinatları ilə. Bütün cavablar JSON, UTF-8.

Giriş

Baza URL:

https://azerbaijanmap.ubermensch.cc/api/v1

API iki data səviyyəsi təqdim edir:

• Baza (/search, /reverse, /details) — inzibati bölgü: şəhər, rayon, qəsəbə, kənd, küçə, Bakı metrosu.
• Tam (/full/…) — baza + 61813 obyekt: məktəb, universitet, xəstəxana, aptek, mağaza, restoran, bank və s.

Axtarış səhv yazılışa dözümlüdür: diakritiksiz (Sabuncu → Sabunçu), hal şəkilçili (Bakının), yazı səhvli (abtek → Aptek), qısaltmalar (bdu → Bakı Dövlət Universiteti) və təbii dil ("Bakının Sabunçu rayonunun Bilgəh qəsəbəsi") işləyir.

Autentifikasiya

Hər sorğu API açarı tələb edir. İki üsulla ötürülür:

# 1) Başlıq (tövsiyə olunur — loglara düşmür)
curl -H "X-API-Key: AÇARINIZ" "https://azerbaijanmap.ubermensch.cc/api/v1/search?q=sabuncu"

# 2) Query parametri
curl "https://azerbaijanmap.ubermensch.cc/api/v1/search?q=sabuncu&key=AÇARINIZ"

Sürət limitləri

Limit aşılanda 429 qayıdır — bir az gözləyib təkrar edin.

GET /search — adla axtarış

# nümunə
curl -H "X-API-Key: AÇAR" "https://azerbaijanmap.ubermensch.cc/api/v1/search?q=mehemedi&limit=2"

{
  "query": "mehemedi", "count": 2, "ms": 21.4,
  "results": [{
    "ad": "Məhəmmədi", "tip": "qəsəbə",
    "yol": "Bakı › Sabunçu › Məhəmmədi",
    "lat": 40.53472, "lon": 49.95275, "uyğunluq": 0.91
  }, …]
}

GET /reverse — koordinatla axtarış

Verilən nöqtəyə (en/uzunluq) ən yaxın yerləri məsafə ilə qaytarır + nöqtənin ərazi konteksti (hansı rayondadır).

curl -H "X-API-Key: AÇAR" "https://azerbaijanmap.ubermensch.cc/api/v1/reverse?lat=40.3777&lon=49.8620&limit=2"

{
  "lat": 40.3777, "lon": 49.862,
  "erazi": { "ad": "Nəsimi", "tip": "alt-rayon",
             "yol": "Bakı › Nəsimi", "mesafe_km": 1.42 },
  "results": [{
    "ad": "Fikrət Əmirov", "tip": "küçə",
    "yol": "Bakı › Nəsimi › Fikrət Əmirov",
    "lat": 40.3781, "lon": 49.8611, "mesafe_km": 0.089
  }, …]
}

GET /details — tam detallar

Tapılan yerin bütün alt-qeydləri: rayonun qəsəbə/kənd/küçə siyahısı, metro stansiyasının strukturu və s. Test tokeni ilə əlçatan deyil.

curl -H "X-API-Key: AÇAR" "https://azerbaijanmap.ubermensch.cc/api/v1/details?q=Bilgəh"

/full/* — obyektlərlə (məktəb, aptek, mağaza…)

Eyni imzalı üç endpoint — baza + 61813 obyekt üzərində işləyir:

# rayon + kateqoriya axtarışı
curl -H "X-API-Key: AÇAR" "https://azerbaijanmap.ubermensch.cc/api/v1/full/search?q=yasamal çayxana"

# tip filtri ilə
curl -H "X-API-Key: AÇAR" "https://azerbaijanmap.ubermensch.cc/api/v1/full/search?q=nizami&tip=Apteklər,küçə"

GET /health

Açarsız sağlamlıq yoxlaması: {"status": "ok", "records": …}

POST /trial-token — test tokeni

2 sorğuluq pulsuz token — ana səhifədəki düymə ilə almaq ən asandır. Cihaz başına bir token, IP limiti var.

Xəta kodları

Embed widget — quraşdırma

Xəritəni saytınıza bir script taqı ilə əlavə edin — üçüncü tərəf kitabxana yüklənmir, hər şey bizim serverdən gəlir:

<div id="az-map" style="height:420px"></div>
<script src="https://azerbaijanmap.ubermensch.cc/embed.js"
        data-key="EMBED_AÇARINIZ"
        data-mode="map"
        data-target="#az-map"></script>

Xəritənin küncündəki yazı defolt «CC | AzərbaycanMap»-dır; açar verilərkən admin tərəfindən dəyişdirilə bilər. Canlı demolar: Nümunələr səhifəsi.

Rejimlər (data-mode)

Bütün parametrlər (data-atributlar)

JS API ilə də çağırıla bilər (tam custom kart daxil):

AzMap.render('#el', { key:'AÇAR', mode:'category', types:'Tibb',
  card: m => `<b>${m.ad}</b><br>☎ <a href="tel:012">012</a>` });

Kod nümunələri

Python (requests)

import requests

BASE = "https://azerbaijanmap.ubermensch.cc/api/v1"
HEADERS = {"X-API-Key": "AÇARINIZ"}

# 1) Adla axtarış
r = requests.get(f"{BASE}/search", params={"q": "yasamal aptek", "limit": 5},
                 headers=HEADERS, timeout=10)
r.raise_for_status()
for yer in r.json()["results"]:
    print(f"{yer['ad']} — {yer['yol']} ({yer['lat']}, {yer['lon']})")

# 2) Koordinatla axtarış (reverse)
r = requests.get(f"{BASE}/reverse",
                 params={"lat": 40.3777, "lon": 49.8620, "limit": 5},
                 headers=HEADERS, timeout=10)
data = r.json()
print("Ərazi:", data["erazi"]["yol"])
for yer in data["results"]:
    print(f"{yer['mesafe_km']} km — {yer['ad']} ({yer['tip']})")

# 3) Obyektlərlə tam axtarış (məktəb, aptek, mağaza…)
r = requests.get(f"{BASE}/full/search", params={"q": "bdu"},
                 headers=HEADERS, timeout=10)
print(r.json()["results"][0]["ad"])   # Bakı Dövlət Universiteti

JavaScript (fetch)

const BASE = "https://azerbaijanmap.ubermensch.cc/api/v1";
const KEY  = "AÇARINIZ";

async function axtar(q) {
  const r = await fetch(
    `${BASE}/full/search?q=${encodeURIComponent(q)}&limit=5`,
    { headers: { "X-API-Key": KEY } });
  if (!r.ok) throw new Error((await r.json()).detail || r.status);
  return (await r.json()).results;
}

async function enYaxin(lat, lon) {
  const r = await fetch(
    `${BASE}/full/reverse?lat=${lat}&lon=${lon}&limit=10`,
    { headers: { "X-API-Key": KEY } });
  const d = await r.json();
  console.log("Ərazi:", d.erazi.yol);
  return d.results;   // hər biri: {ad, tip, yol, lat, lon, mesafe_km}
}

// istifadəçinin konumu ilə:
navigator.geolocation.getCurrentPosition(async p => {
  const yaxinlar = await enYaxin(p.coords.latitude, p.coords.longitude);
  yaxinlar.forEach(y => console.log(`${y.mesafe_km} km — ${y.ad}`));
});

Açar almaq

Açarlar əl ilə verilir — müraciət formunu doldurun (ad soyad, əlaqə, istifadə səbəbi, sayt/domain), Qiyas sizə dönüş edəcək. Sınamaq üçün 2 sorğuluq test tokeni dərhal alınır.

© Azərbaycan Yer Datası — qiyasturk@gmail.com · t.me/qiyascc