Адресница
РазделыПервый запрос

Документация

Первый запрос за две минуты

API Адресницы ищет адреса по ГАР ФНС и отдаёт все поля адреса: индекс, коды, координаты, метро. Вот как отправить первый запрос.

  1. Аккаунт

    Зарегистрируйтесь по e-mail в личном кабинете. Карта не нужна.

  2. Ключ

    Создайте ключ: публичный для сайта или секретный для сервера.

  3. Запрос

    Отправьте запрос с ключом в заголовке. Ответ — JSON.

Адрес API и ключ

Все запросы идут на https://api.adresnitsa.ru. Ключ передайте в заголовке Authorization:

Заголовок
Authorization: Token ВАШ_КЛЮЧ

Форма Bearer ВАШ_КЛЮЧ тоже работает. Без ключа сервер ответит 401 (ошибки и лимиты).

Два вида ключей

Для сайтаПубличный ключ gar_pub_…

Его видно в коде страницы, поэтому он ограничен:

  • работает только с ваших сайтов из списка: example.com или *.example.com;
  • только поиск и координаты: /v1/search, /v1/geolocate и подсказки совместимого режима;
  • свой лимит: 10 000 запросов в день, если не задан другой.
Для сервераСекретный ключ gar_sec_…

Храните его только на сервере:

  • все маршруты, в том числе /v1/details;
  • можно разрешить только свои IP-адреса или сети;
  • общий лимит аккаунта.

Публичный ключ с details=true получает все поля найденных адресов — так же, как секретный.

Первый запрос

Найдём дом по началу адреса. Параметр q — строка, которую ввёл человек, count — сколько подсказок вернуть.

curl
curl -G https://api.adresnitsa.ru/v1/search \
  -H "Authorization: Token ВАШ_КЛЮЧ" \
  --data-urlencode "q=москва сухонская 11" \
  -d count=3
JavaScript
const url = new URL("https://api.adresnitsa.ru/v1/search");
url.search = new URLSearchParams({ q: "москва сухонская 11", count: "3" });
const res = await fetch(url, {
  headers: { Authorization: "Token ВАШ_КЛЮЧ" },
});
const data = await res.json();
Python
import requests

res = requests.get(
    "https://api.adresnitsa.ru/v1/search",
    params={"q": "москва сухонская 11", "count": 3},
    headers={"Authorization": "Token ВАШ_КЛЮЧ"},
    timeout=5,
)
data = res.json()
PHP
<?php
$url = "https://api.adresnitsa.ru/v1/search?" . http_build_query([
    "q" => "москва сухонская 11",
    "count" => 3,
]);
$ctx = stream_context_create(["http" => [
    "header" => "Authorization: Token ВАШ_КЛЮЧ\r\n",
    "ignore_errors" => true,
]]);
$data = json_decode(file_get_contents($url, false, $ctx), true);

Ответ сервера:

Ответ200 OKданные 2026.01.02 v.219
{
  "count": 3,
  "query": "москва сухонская 11",
  "results": [
    {
      "level": 10,
      "guid": "5ee84ac0-eb9a-4b42-b814-2f5f7c27c255",
      "address": "г Москва, ул Сухонская, д 11",
      "id": 26847188,
      "components": ["г Москва", "ул Сухонская", "д 11"]
    },
    {
      "level": 10,
      "guid": "abc31736-35c1-4443-a061-b67c183b590a",
      "address": "г Москва, ул Сухонская, д 11А",
      "id": 27093049,
      "components": ["г Москва", "ул Сухонская", "д 11А"]
    },
    {
      "level": 11,
      "guid": "91a45419-5b64-41ac-b013-4500e4974ec2",
      "address": "г Москва, ул Сухонская, д 11, кв 1",
      "id": 26857926,
      "components": ["г Москва", "ул Сухонская", "д 11", "кв 1"]
    }
  ]
}

В results адреса идут от лучшего к худшему. id и guid — коды объекта в ГАР. Чтобы получить индекс, коды, координаты и метро, добавьте details=true или запросите адрес по коду.

Общие правила

  • Каждый маршрут принимает GET с параметрами в строке запроса или POST с JSON тех же имён (Content-Type: application/json, до 64 КБ).
  • Ответ — JSON в UTF-8. Поля без значения в ответе нет: null не приходит.
  • В каждом ответе есть заголовок X-Data-Version — версия данных ГАР. Данные обновляем каждую неделю.
  • CORS открыт: публичный ключ работает прямо из браузера.
  • Лимит аккаунта — 20 000 запросов в день и 30 в секунду на ключ. Что считается запросом — в разделе ошибки и лимиты.

Что дальше