API Sənədləri

Azərbaycanın yer datası — 66 rayon, 4248 kənd, 17283 küçə, 114903 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, /suggest, /resolve, /reverse, /address, /nearby, /details) — inzibati bölgü: şəhər, rayon, qəsəbə, kənd, küçə, Bakı metrosu.
• Tam (/full/…) — baza + 114903 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
  }, …]
}

POST /geocode-batch — toplu geokodlaşdırma

Ad / ünvan siyahısını bir sorğuda koordinatlara çevir — biznes CSV-ləri, kütləvi geokodlaşdırma üçün (maks 100 sorğu). Hər element üçün ən yaxşı koordinatlı, etibarlı uyğunluq qaytarılır.

# nümunə
curl -X POST -H "X-API-Key: AÇAR" -H "Content-Type: application/json" \
  -d '{"queries":["Fəvvarələr meydanı","Gəncə","28 May metro"]}' \
  "https://azerbaijanmap.ubermensch.cc/api/v1/geocode-batch"

{
  "say": 3, "tapıldı": 3, "ms": 41.2,
  "nəticələr": [{
    "sorğu": "Fəvvarələr meydanı", "tapıldı": true,
    "ad": "Fəvvarələr Meydanı", "lat": 40.371, "lon": 49.837, "uyğunluq": 1.0
  }, …]
}

Xəritə xidmətləri və canlı data

Widget-də (nümunələrdə) olan bütün funksiyalar həm də birbaşa API kimi — açarla, domenə bağlı olmadan (server-server də işləyir). Marşrut, izoxron, hava keyfiyyəti, zəlzələ, külək, təyyarə, görməli yerlər, metro.

# marşrut (turn-by-turn)
curl -H "X-API-Key: AÇAR" "https://azerbaijanmap.ubermensch.cc/api/v1/route?f=40.38,49.85&t=40.41,49.87&profile=car"
# → { "m":3540, "s":612, "pts":[[40.38,49.85],…], "addimlar":[…] }

# hava keyfiyyəti
curl -H "X-API-Key: AÇAR" "https://azerbaijanmap.ubermensch.cc/api/v1/hava"
# → { "points":[{"lat":40.4,"lon":49.9,"aqi":42,"pm25":8.1,…}], "menbe":"Open-Meteo" }

Avtobus — marşrutlar və dayanacaqlar (AYNA)

Azərbaycan ictimai nəqliyyatı — 208 marşrut (BakuBus və s.). Üç endpoint: ünvandan/nöqtədən keçən avtobuslar, bir marşrutun dayanacaqları, tam siyahı.

Verilən ünvandan/nöqtədən keçən avtobuslar + yaxın dayanacaqlar. Ünvan verilsə geokodlaşdırılır, ya da birbaşa koordinat.

curl -H "X-API-Key: AÇAR" "https://azerbaijanmap.ubermensch.cc/api/v1/bus/nearby?unvan=28 May metrosu"

{
  "lat": 40.3794, "lon": 49.8501, "radius_m": 500,
  "xett_sayi": 24, "xetler": ["1","2","4", …, "H1"],
  "dayanacaq_sayi": 15,
  "dayanacaqlar": [{ "ad":"28 May m/st", "lat":40.3796, "lon":49.8502,
                     "mesafe_m":20, "xetler":["10","120E"] }, …]
}

Bir marşrutun sıralı DAYANACAQLARI + tarif, müddət, uzunluq, daşıyıcı, yol həndəsəsi (paths).

curl -H "X-API-Key: AÇAR" "https://azerbaijanmap.ubermensch.cc/api/v1/bus/route?nomre=1"

{
  "nomre": "1", "bas": "Neftçilər m/st", "son": "28 May m/st",
  "tarif": "0.60 AZN", "muddet_deq": 43, "uzunluq": 25.8,
  "dayanacaq_sayi": 45,
  "dayanacaqlar": [{ "ad":"Neftçilər m/st", "lat":40.4116, "lon":49.9420 }, …]
}

Bütün 208 marşrutun qısa siyahısı: nömrə, başlanğıc–son, tarif, müddət, dayanacaq sayı.

curl -H "X-API-Key: AÇAR" "https://azerbaijanmap.ubermensch.cc/api/v1/bus/routes"

GET /resolve — çox-yerli həlledici (bot inteqrasiyası)

İstifadəçi mətnindən çıxan yer siyahısını («Koroğlu, Qara Qarayev, Neftçilər…») hissə-hissə həll edir: hər hissə üçün ən yaxşı uyğunluq + koordinat + rayon konteksti, üstəgəl bütün tapılanların mərkəzi və bbox-u. Tək yer də işləyir — aqreqator/bot sistemləri üçün universal həlledici.

curl -H "X-API-Key: AÇAR" "https://azerbaijanmap.ubermensch.cc/api/v1/resolve?q=Koroğlu, Qara Qarayev, Həzi Aslanov&tip=metro"

{
  "verdict": "full", "n": 3, "tapilan": 3,
  "items": [{
    "q": "Koroğlu", "tapildi": true,
    "ad": "Koroğlu", "tip": "metro",
    "lat": 40.4209, "lon": 49.9181,
    "erazi": { "ad": "Nizami", "tip": "alt-rayon", … }
  }, …],
  "center": [40.4021, 49.9312], "bbox": [40.3722, 49.8016, 40.4253, 49.9535],
  "erazi": { "ad": "Nizami", … }
}

GET /stats — platforma statistikası (açıq)

Data miqyasının canlı statistikası — açar tələb olunmur. İnzibati saylar, obyekt (POI) sayı, məlumat zənginliyi (telefon/sayt/bina nömrəsi/poçt kodu/şəkil), kateqoriya bölgüsü, mənbələr. 30 dəq keşli.

curl "https://azerbaijanmap.ubermensch.cc/api/v1/stats"

{
  "cemi_qeyd": 128682,
  "obyekt": { "cemi": 106950, "telefonlu": 17041,
              "saytli": 11244, "bina_nomreli": 12441,
              "poct_kodlu": 59661, "sekilli": 578 },
  "unvan_noqtesi": 23723,
  "kateqoriyalar": [ { "ad": "Ticarət", "say": 38740 }, … ],
  "menbe": [ { "source": "gomap", "n": 61813 }, … ]
}

GET /categories — kateqoriya ağacı

POI kateqoriya ağacı: 9 əsas kateqoriya → 135 subkateqoriya, saylarla. Bu adlar search/suggest/markers-də tip= filtri kimi işlədilir (məs. tip=Apteklər).

curl -H "X-API-Key: AÇAR" "https://azerbaijanmap.ubermensch.cc/api/v1/categories"

{ "kateqoriyalar": [
  { "ad": "Tibb", "say": 4796, "subler": [
      { "ad": "Poliklinikalar", "say": 2346 },
      { "ad": "Apteklər", "say": 1675 }, … ] }, … ] }

GET /suggest — autocomplete (yazdıqca təklif)

Prefiks-öncəlikli, typo-dözümlü təkliflər — axtarış qutusu üçün. Metro/rayon/qəsəbə küçə və POI-lərin hamısı; hər nəticədə highlight aralığı (hi) və tipi. Çox sürətli (keşli).

curl -H "X-API-Key: AÇAR" "https://azerbaijanmap.ubermensch.cc/api/v1/suggest?q=koro&limit=3"

{
  "query": "koro", "count": 3,
  "results": [{
    "ad": "Koroğlu", "tip": "metro",
    "yol": "Bakı › Metro › M1",
    "lat": 40.4209, "lon": 49.9181,
    "hi": [0, 4]      // "Koro" — 0-dan 4 simvol qalın
  }, …]
}

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 /nearby — ətrafımda nə var

Nöqtə ətrafında (radius metr, ≤5000) obyektlər məsafəyə görə sıralı: ən yaxın aptek, ATM, xəstəxana, market… tip= ilə süz. Grid indeksi ilə çox sürətli (~3ms).

curl -H "X-API-Key: AÇAR" "https://azerbaijanmap.ubermensch.cc/api/v1/nearby?lat=40.3777&lon=49.8320&tip=Apteklər&radius=400"

{
  "radius": 400, "count": 5,
  "results": [{
    "ad": "'Çeburaşka' apteki", "tip": "Apteklər",
    "lat": 40.3778, "lon": 49.8325, "mesafe_m": 55
  }, …]
}

GET /address — strukturlu ünvan

Nöqtənin tam ünvanı: inzibati zəncir (şəhər › rayon) + ən yaxın qəsəbə/kənd + ən yaxın küçə (≤1.5 km) + ≤400m radiusda ən yaxın obyekt (aptek, məktəb, mağaza…). yol — insana oxunaqlı tam ünvan.

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

{
  "tam_unvan": "Bakı › Nərimanov › Ağa Nemətulla küç. 78, AZ1052",
  "yol": "Bakı › Nərimanov › M.Uluqbek küçəsi",
  "inzibati": { "ad": "Nərimanov", "tip": "alt-rayon" },
  "kuce":  { "ad": "M.Uluqbek küçəsi", "mesafe_m": 227 },
  "bina":  { "kuce": "Ağa Nemətulla küç.", "bina": "78", "mesafe_m": 24 },
  "zip":   "AZ1052",
  "obyekt": { "ad": "'Təndir' kulinariya evi", "mesafe_m": 8 }
}

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 + 114903 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