Address Resolution Admin
API docs & examples

Методы работы с API

Эта страница — краткая рабочая шпаргалка по основным методам сервиса: поиск адресов, reverse geocoding, обогащение координат и адресов, маршрут, batch-запросы и несколько legacy-методов для совместимости.

Bearer JWT X-API-Key GET / POST Python JavaScript
← Dashboard Access & tokens

Как авторизоваться

1. API key

Для серверных интеграций удобнее всего использовать X-API-Key. Ключи создаются на странице Access & tokens.

2. Bearer token

Для запросов от администратора подходит JWT в заголовке Authorization: Bearer ... или браузерная cookie-сессия.

Для большинства автоматизаций лучше брать API key. Для работы в браузере и админке обычно достаточно текущей сессии.

Основные методы

GET /api/v1/search
Поиск адреса / partial-address: строка запроса, город, язык и лимит.
Параметры: q, city, language, limit
GET /api/v1/reverse
Обратное геокодирование по координатам.
Параметры: lat, lng, limit
POST /api/v1/polygon/search
Поиск объектов внутри WKT-полигона или по точке.
Тело: polygon_wkt или lat/lng
POST /api/v1/geo/by-address
Обогащение адреса: координаты, ячейка, сектор, связанные данные.
GET /api/v1/geo/by-coordinates
Обогащение точки по координатам.
POST /api/v1/route
Полный маршрут по списку точек: enriched points, distance, duration, geometry, legs.
POST /api/v1/routes/preview
Компактный map-ready маршрут для клиента: GeoJSON LineString, bbox, waypoints, distance и duration.
Важно: GeoJSON coordinates и bbox используют порядок [lng, lat].
POST /api/v1/geo/batch
Batch-обогащение точек, включая маршрут.

Legacy / compatibility

Эти методы оставлены для старых интеграций. Новые клиенты лучше строить на /api/v1/*.

GET /get/cell
Возвращает ячейку для точки.
GET /get_sector
Возвращает список секторов.
POST /get_sectors
Накладывает сектора на массив точек.
POST /get_full_route
Старый endpoint для маршрута с полным разбором.
POST /get/all-data
Batch-обогащение в legacy формате.

Python examples

Примеры используют requests и заголовок X-API-Key. 

import os
import requests

BASE_URL = os.getenv("GEOSVC_URL", "http://localhost:8081")
API_KEY = os.environ["GEOSVC_API_KEY"]

response = requests.get(
    f"{BASE_URL}/api/v1/reverse",
    params={"lat": 50.4501, "lng": 30.5234, "limit": 3},
    headers={"X-API-Key": API_KEY},
    timeout=30,
)
response.raise_for_status()
for item in response.json()["results"]:
    print(item["name"], item.get("distance_m"))
import os
import requests

BASE_URL = os.getenv("GEOSVC_URL", "http://localhost:8081")
API_KEY = os.environ["GEOSVC_API_KEY"]

payload = {
    "points": [
        {"name": "A", "lat": 50.4501, "lng": 30.5234},
        {"name": "B", "lat": 50.4547, "lng": 30.5310},
    ]
}

response = requests.post(
    f"{BASE_URL}/api/v1/geo/batch",
    json=payload,
    headers={"X-API-Key": API_KEY},
    timeout=30,
)
response.raise_for_status()
print(response.json())

JavaScript examples

Подходит для Node.js и браузерных интеграций. Заголовок тот же: X-API-Key. 

const baseUrl = process.env.GEOSVC_URL ?? "http://localhost:8081";
const apiKey = process.env.GEOSVC_API_KEY;

const response = await fetch(`${baseUrl}/api/v1/geo/by-address`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": apiKey,
  },
  body: JSON.stringify({
    query: "Крещатик 1",
    city: "Киев",
  }),
});

if (!response.ok) throw new Error(await response.text());
console.log(await response.json());
const baseUrl = process.env.GEOSVC_URL ?? "http://localhost:8081";
const apiKey = process.env.GEOSVC_API_KEY;

const response = await fetch(`${baseUrl}/api/v1/route`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": apiKey,
  },
  body: JSON.stringify({
    points: [
      { name: "A", lat: 50.4501, lng: 30.5234 },
      { name: "B", lat: 50.4547, lng: 30.5310 },
    ],
  }),
});

if (!response.ok) throw new Error(await response.text());
console.log(await response.json());
const baseUrl = process.env.GEOSVC_URL ?? "http://localhost:8081";
const apiKey = process.env.GEOSVC_API_KEY;

const response = await fetch(`${baseUrl}/api/v1/routes/preview`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": apiKey,
  },
  body: JSON.stringify({
    points: [
      { name: "pickup", lat: 50.5055597, lng: 30.4175632 },
      { name: "dropoff", lat: 50.4501, lng: 30.5234 },
    ],
  }),
});

if (!response.ok) throw new Error(await response.text());
const preview = await response.json();

// preview.geometry is GeoJSON LineString: coordinates are [lng, lat]
// preview.bbox is [minLng, minLat, maxLng, maxLat]
console.log(preview.geometry, preview.bbox);

Практические подсказки