Документація адреси API

Огляд API

Структуровані адресні дані України через HTTP REST API

GeoData Ukraine API — це SaaS-сервіс, який надає доступ до структурованих адресних даних України. Дані доступні лише для читання (read-only) і містять повну ієрархію адресних компонентів:

🗺️ Область → 📍 Район → 🏙️ Місто → 🛣️ Вулиця → 🏠 Будинок → 🌍 GPS координати

Базова URL: https://geodataua.runasp.net/api

🔑 Автентифікація

Усі запити до бізнес-ендпоінтів вимагають API-ключа

API-ключ передається у заголовку кожного запиту:

X-API-Key: <YOUR_API_KEY>

API-ключ видається при реєстрації клієнта в особистому кабінеті.

💡 Примітка: Ендпоінти /api/ping працюють без автентифікації.

⚙️ Загальні принципи

HTTP методи, формати, пагінація та коди відповідей

HTTP методи

Метод	Опис
`GET`	Отримання даних (єдиний дозволений метод)

Формат відповіді

Усі відповіді повертаються у форматі application/json; charset=utf-8.

Відповіді містять дані одночасно українською та англійською мовами у відповідних полях (суфікси UA / EN).

Пагінація

Ендпоінти міст, вулиць та будинків підтримують пагінацію:

Параметр	Тип	За замовчуванням	Опис
`pageNumber`	int	1	Номер сторінки (починаючи з 1)
`pageSize`	int	25	Кількість елементів на сторінці (макс. 25)

Фільтрація через параметр searchName — пошук за початком назви.

💡 Ендпоінти регіонів та районів повертають повний список без пагінації.

Коди відповідей

Код	Опис
200	Успішний запит
400	Невалідні параметри запиту або невалідний API-ключ
404	Ресурс не знайдено
500	Внутрішня помилка сервера

Формат помилки:

{
  "message": "Помилка при отриманні регіонів",
  "error": "Опис помилки валідації"
}

🏓 Health Check (Ping)

Перевірка доступності API без автентифікації

GET /api/ping

Перевірка доступності API.

Приклад відповіді 200

{
  "status": "ok",
  "timestamp": "2026-03-04T12:00:00Z",
  "message": "GeoData UA API працює"
}

GET /api/ping/echo/{text}

Ехо-запит — повертає надісланий текст.

Приклад запиту

GET /api/ping/echo/hello

Приклад відповіді 200

{
  "echo": "hello"
}

GET /api/ping/info

Інформація про сервер.

Приклад відповіді 200

{
  "app": "GeoData UA",
  "environment": "Production",
  "framework": ".NET 8.0.x",
  "os": "Linux 5.15.x"
}

🗺️ Області (Regions)

Отримання списку областей України

GET /api/regions

Повертає повний список всіх областей без пагінації.

Приклад запиту (curl)

curl -X 'GET' \
  'https://geodataua.runasp.net/api/Regions' \
  -H 'accept: application/json' \
  -H 'X-API-Key: YOUR_API_KEY'

Приклад відповіді 200

[
  {
    "regionId": 261,
    "nameUA": "Автономна Республіка Крим",
    "nameEN": "Avtonomna Respublika Krym",
    "katottg": "UA01000000000013043",
    "katottgType": "O"
  },
  {
    "regionId": 262,
    "nameUA": "Вінницька",
    "nameEN": "Vinnytska",
    "katottg": "UA05000000000010236",
    "katottgType": "O"
  },
  {
    "regionId": 263,
    "nameUA": "Волинська",
    "nameEN": "Volynska",
    "katottg": "UA07000000000024379",
    "katottgType": "O"
  }
  // ... всі 27 областей
]

GET /api/regions/{id}

Отримати область за ID.

Параметр	Тип	Обов'язковий	Опис
`id`	int	Так	ID області (> 0)

Приклад відповіді 200

{
  "regionId": 262,
  "nameUA": "Вінницька",
  "nameEN": "Vinnytska",
  "katottg": "UA05000000000010236",
  "katottgType": "O"
}

Приклад відповіді 404

{
  "message": "Регіон з ID 999 не знайдено"
}

📍 Райони (Districts)

Отримання списку районів за областю

GET /api/districts?regionId={regionId}

Повертає повний список районів для вказаної області без пагінації.

Параметр	Тип	Обов'язковий	Опис
`regionId`	int	Так	ID області (> 0)

Приклад запиту (curl)

curl -X 'GET' \
  'https://geodataua.runasp.net/api/Districts?regionId=262' \
  -H 'accept: application/json' \
  -H 'X-API-Key: YOUR_API_KEY'

Приклад відповіді 200

[
  {
    "districtId": 291,
    "regionId": 262,
    "districtNameUA": "Вінницький",
    "districtNameEN": "VINNYTSKYI",
    "katottg": "UA05020000000026686",
    "katottgType": "P"
  },
  {
    "districtId": 292,
    "regionId": 262,
    "districtNameUA": "Гайсинський",
    "districtNameEN": "HAISYNSKYI",
    "katottg": "UA05040000000050292",
    "katottgType": "P"
  },
  {
    "districtId": 293,
    "regionId": 262,
    "districtNameUA": "Жмеринський",
    "districtNameEN": "ZHMERYNSKYI",
    "katottg": "UA05060000000061926",
    "katottgType": "P"
  }
]

🏙️ Міста / Населені пункти (Cities)

Отримання списку міст у районі з пагінацією та пошуком

GET /api/cities?districtId={districtId}&pageNumber=&pageSize=&searchName=

Параметр	Тип	Обов'язковий	За замовч.	Опис
`districtId`	int	Так	—	ID району (> 0)
`pageNumber`	int	Так	1	Номер сторінки (> 0)
`pageSize`	int	Так	25	Розмір сторінки (1–25)
`searchName`	string	Ні	null	Пошук за початком назви міста

Приклад запиту (curl)

curl -X 'GET' \
  'https://geodataua.runasp.net/api/Cities?districtId=291&pageNumber=1&pageSize=25&searchName=він' \
  -H 'accept: application/json' \
  -H 'X-API-Key: YOUR_API_KEY'

Приклад відповіді 200

{
  "cities": [
    {
      "cityId": 1057,
      "districtId": 291,
      "cityNameUA": "Вінниця",
      "cityNameEN": "Vinnytsia",
      "cityTypeUA": "місто",
      "cityTypeEN": "City",
      "shortCityTypeUA": "м.",
      "oldCityNameUA": null,
      "katottg": "UA05020030010063857",
      "katottgType": "M",
      "koatuu": "0510100000",
      "population": 369750,
      "longitude": 28.49268,
      "latitude": 49.23702,
      "isDistrictCenter": true,
      "ownof": "Вінницька"
    },
    {
      "cityId": 1060,
      "districtId": 291,
      "cityNameUA": "Вінницькі Хутори",
      "cityNameEN": "Vinnytski Khutory",
      "cityTypeUA": "село",
      "cityTypeEN": "Village",
      "shortCityTypeUA": "с.",
      "oldCityNameUA": null,
      "katottg": "UA05020030040041811",
      "katottgType": "C",
      "koatuu": "0520681003",
      "population": 9227,
      "longitude": 28.550431,
      "latitude": 49.209466,
      "isDistrictCenter": false,
      "ownof": "Вінницька"
    }
  ],
  "totalPages": 1
}

🛣️ Вулиці (Streets)

Отримання списку вулиць у місті з пагінацією та пошуком

GET /api/streets?cityId={cityId}&pageNumber=&pageSize=&searchName=

Параметр	Тип	Обов'язковий	За замовч.	Опис
`cityId`	int	Так	—	ID міста (> 0)
`pageNumber`	int	Так	1	Номер сторінки (> 0)
`pageSize`	int	Так	25	Розмір сторінки (1–25)
`searchName`	string	Ні	null	Пошук за початком назви вулиці

Приклад запиту (curl)

curl -X 'GET' \
  'https://geodataua.runasp.net/api/Streets?cityId=1057&pageNumber=1&pageSize=25&searchName=шев' \
  -H 'accept: application/json' \
  -H 'X-API-Key: YOUR_API_KEY'

Приклад відповіді 200

{
  "streets": [
    {
      "streetId": 171630,
      "cityId": 1057,
      "streetNameUA": "Шевченка",
      "streetNameEN": "SHEVCHENKA",
      "streetTypeUA": "вулиця",
      "streetTypeEN": "street",
      "shortStreetTypeUA": "вул.",
      "oldStreetNameUA": null
    },
    {
      "streetId": 171675,
      "cityId": 1057,
      "streetNameUA": "Шевченка",
      "streetNameEN": "SHEVCHENKA",
      "streetTypeUA": "тупик",
      "streetTypeEN": "tupyk",
      "shortStreetTypeUA": "тупик",
      "oldStreetNameUA": null
    }
  ],
  "totalPages": 1
}

🏠 Будинки (Houses)

Отримання списку будинків на вулиці та GPS-координат будинку

GET /api/Houses/Numbers?streetId={streetId}&pageNumber=&pageSize=&searchName=

Повертає список будинків на вулиці з пагінацією та пошуком за номером.

Параметр	Тип	Обов'язковий	За замовч.	Опис
`streetId`	int	Так	—	ID вулиці (> 0)
`pageNumber`	int	Так	1	Номер сторінки (> 0)
`pageSize`	int	Так	25	Розмір сторінки (1–25)
`searchName`	string	Ні	null	Пошук за початком номера будинку

Приклад запиту (curl)

curl -X 'GET' \
  'https://geodataua.runasp.net/api/Houses/Numbers?streetId=171630&pageNumber=1&pageSize=25' \
  -H 'accept: application/json' \
  -H 'X-API-Key: YOUR_API_KEY'

Приклад відповіді 200

{
  "houses": [
    {
      "houseId": 4424748,
      "streetId": 171630,
      "houseNumberUA": "4",
      "postCode": "21036"
    },
    {
      "houseId": 4424749,
      "streetId": 171630,
      "houseNumberUA": "5А",
      "postCode": "21036"
    },
    {
      "houseId": 4424750,
      "streetId": 171630,
      "houseNumberUA": "6",
      "postCode": "21036"
    },
    {
      "houseId": 4424751,
      "streetId": 171630,
      "houseNumberUA": "7",
      "postCode": "21036"
    }
  ],
  "totalPages": 3
}

GET /api/Houses/Gps?houseId={houseId}

Повертає GPS-координати (широту та довготу) для вказаного будинку. Якщо визначити не вдалося, то будуть повернені 0 значення.

Параметр	Тип	Обов'язковий	Опис
`houseId`	int	Так	ID будинку (> 0)

Приклад запиту (curl)

curl -X 'GET' \
  'https://geodataua.runasp.net/api/Houses/Gps?houseId=22' \
  -H 'accept: application/json' \
  -H 'X-API-Key: YOUR_API_KEY'

Приклад відповіді 200

{
  "latitude": 49.8190824,
  "longitude": 30.0724545
}

📋 Зведена таблиця ендпоінтів

Короткий огляд усіх доступних ендпоінтів

Метод	Ендпоінт	Пагінація	Опис
GET	`/api/ping`	Ні	Перевірка доступності API
GET	`/api/ping/echo/{text}`	Ні	Ехо-запит
GET	`/api/ping/info`	Ні	Інформація про сервер
GET	`/api/regions`	Ні	Список всіх областей
GET	`/api/regions/{id}`	Ні	Область за ID
GET	`/api/districts?regionId=`	Ні	Райони за областю
GET	`/api/cities?districtId=&...`	Так	Міста в районі
GET	`/api/streets?cityId=&...`	Так	Вулиці в місті
GET	`/api/Houses/Numbers?streetId=&...`	Так	Будинки на вулиці
GET	`/api/Houses/Gps?houseId=`	Ні	GPS-координати будинку

💻 Приклад інтеграції (JavaScript)

Швидкий старт для вашого додатку

const API_BASE = 'https://geodataua.runasp.net/api';
const API_KEY = 'your-api-key';

const headers = {
  'X-API-Key': API_KEY,
  'Accept': 'application/json'
};

// Отримати всі області
async function getRegions() {
  const response = await fetch(`${API_BASE}/regions`, { headers });
  return response.json();
}

// Отримати райони за областю
async function getDistricts(regionId) {
  const response = await fetch(
    `${API_BASE}/districts?regionId=${regionId}`,
    { headers }
  );
  return response.json();
}

// Отримати міста в районі з пагінацією та пошуком
async function getCities(districtId, searchName = '', page = 1, size = 25) {
  const params = new URLSearchParams({ districtId, pageNumber: page, pageSize: size });
  if (searchName) params.set('searchName', searchName);
  const response = await fetch(`${API_BASE}/cities?${params}`, { headers });
  return response.json();
}

// Отримати вулиці в місті
async function getStreets(cityId, searchName = '', page = 1, size = 25) {
  const params = new URLSearchParams({ cityId, pageNumber: page, pageSize: size });
  if (searchName) params.set('searchName', searchName);
  const response = await fetch(`${API_BASE}/streets?${params}`, { headers });
  return response.json();
}

// Отримати будинки на вулиці
async function getHouses(streetId, searchName = '', page = 1, size = 25) {
  const params = new URLSearchParams({ streetId, pageNumber: page, pageSize: size });
  if (searchName) params.set('searchName', searchName);
  const response = await fetch(`${API_BASE}/Houses/Numbers?${params}`, { headers });
  return response.json();
}

// Отримати GPS-координати будинку
async function getHouseGps(houseId) {
  const response = await fetch(`${API_BASE}/Houses/Gps?houseId=${houseId}`, { headers });
  return response.json();
}

📖 Документація адреси API

Зміст

Огляд API

🔑 Автентифікація

⚙️ Загальні принципи

HTTP методи

Формат відповіді

Пагінація

Коди відповідей

Формат помилки:

🏓 Health Check (Ping)

Приклад відповіді 200

Приклад запиту

Приклад відповіді 200

Приклад відповіді 200

🗺️ Області (Regions)

Приклад запиту (curl)

Приклад відповіді 200

Приклад відповіді 200

Приклад відповіді 404

📍 Райони (Districts)

Приклад запиту (curl)

Приклад відповіді 200

🏙️ Міста / Населені пункти (Cities)

Приклад запиту (curl)

Приклад відповіді 200

🛣️ Вулиці (Streets)

Приклад запиту (curl)

Приклад відповіді 200

🏠 Будинки (Houses)

Приклад запиту (curl)

Приклад відповіді 200

Приклад запиту (curl)

Приклад відповіді 200

📋 Зведена таблиця ендпоінтів

💻 Приклад інтеграції (JavaScript)