ДокументацияПереход

Совместимый режим

Совместимый режим: самый популярный формат подсказок. Если подсказки адресов у вас уже работают в этом формате, поменяйте адрес сервера — виджет и ваш код работают как раньше.

Одна строка

Новый адрес сервера:

Адрес сервера

https://api.adresnitsa.ru/suggestions/api/4_1/rs

Заголовок с ключом тот же, ключ — из личного кабинета Адресницы:

Заголовок

Authorization: Token ВАШ_КЛЮЧ

Виджет подсказок, который уже стоит у вас на странице, остаётся. Меняются две строки: адрес сервера и ключ. Для сайта возьмите публичный ключ и впишите свой сайт в его список.

JavaScript

$("#address").suggestions({
  serviceUrl: "https://api.adresnitsa.ru/suggestions/api/4_1/rs", // новый адрес  token: "ВАШ_КЛЮЧ", // ключ Адресницы  type: "ADDRESS"
});

Маршруты

Все пути — от адреса сервера выше. POST с JSON или GET с query и count.

Путь	Ключ	Что делает
suggest/address	любой	Подсказки по строке `query`.
findById/address	секретный	Адрес по коду: GUID объекта ГАР (ФИАС) или код КЛАДР.
geolocate/address	любой	Адреса рядом с точкой: `lat`, `lon`, `radius_meters` (до 1000, по умолчанию 100), `count`.
status/address	любой	Виджет спрашивает при запуске, работает ли сервис. Не считается.
iplocate/address	любой	Город по IP-адресу. Всегда `{"location": null}`: виджет просто не поднимает город. Не считается.

Параметры подсказок

Параметр	Что делает
count	Сколько подсказок: 1–20, по умолчанию 10.
locations	Искать только здесь: по `*_fias_id`, `kladr_id`, `region_iso_code` или по названиям (`region`, `city`, `settlement`, `street` и т. д.). Несколько мест — «или».
locations_boost	Поднять выше адреса в этих местах, не убирая остальные.
from_bound, to_bound	Только уровни от и до: `country`, `region`, `area`, `city`, `city_district`, `settlement`, `street`, `house`, `flat`.
restrict_value	Не повторять в подсказке часть из `locations`: «ул Баумана» вместо «г Казань, ул Баумана».

Неизвестные параметры и значения null сервер пропускает, как и в привычном формате.

Пример: подсказки

curl

curl https://api.adresnitsa.ru/suggestions/api/4_1/rs/suggest/address \
  -H "Authorization: Token ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{"query": "москва сухонская 11", "count": 2}'

JavaScript

const res = await fetch("https://api.adresnitsa.ru/suggestions/api/4_1/rs/suggest/address", {
  method: "POST",
  headers: {
    Authorization: "Token ВАШ_КЛЮЧ",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: "москва сухонская 11", count: 2 }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.adresnitsa.ru/suggestions/api/4_1/rs/suggest/address",
    json={"query": "москва сухонская 11", "count": 2},
    headers={"Authorization": "Token ВАШ_КЛЮЧ"},
    timeout=5,
)
data = res.json()

PHP

<?php
$body = json_encode(["query" => "москва сухонская 11", "count" => 2], JSON_UNESCAPED_UNICODE);
$ctx = stream_context_create(["http" => [
    "method" => "POST",
    "header" => "Authorization: Token ВАШ_КЛЮЧ\r\n" .
        "Content-Type: application/json\r\n",
    "content" => $body,
    "ignore_errors" => true,
]]);
$data = json_decode(file_get_contents("https://api.adresnitsa.ru/suggestions/api/4_1/rs/suggest/address", false, $ctx), true);

Ответ200 OKданные 2026.01.02 v.219

{
  "suggestions": [
    {
      "value": "г Москва, ул Сухонская, д 11",
      "unrestricted_value": "127642, г Москва, ул Сухонская, д 11",
      "data": {
        "postal_code": "127642",
        "country": "Россия",
        "country_iso_code": "RU",
        "federal_district": "Центральный",
        "region_fias_id": "0c5b2444-70a0-4932-980c-b4dc0d3f02b5",
        "region_kladr_id": "7700000000000",
        "region_iso_code": "RU-MOW",
        "region_with_type": "г Москва",
        "region_type": "г",
        "region_type_full": "город",
        "region": "Москва",
        "area_fias_id": null,
        "area_kladr_id": null,
        "area_with_type": null,
        "area_type": null,
        "area_type_full": null,
        "area": null,
        "city_fias_id": "0c5b2444-70a0-4932-980c-b4dc0d3f02b5",
        "city_kladr_id": "7700000000000",
        "city_with_type": "г Москва",
        "city_type": "г",
        "city_type_full": "город",
        "city": "Москва",
        "city_area": null,
        "city_district_fias_id": null,
        "city_district_kladr_id": null,
        "city_district_with_type": null,
        "city_district_type": null,
        "city_district_type_full": null,
        "city_district": null,
        "settlement_fias_id": null,
        "settlement_kladr_id": null,
        "settlement_with_type": null,
        "settlement_type": null,
        "settlement_type_full": null,
        "settlement": null,
        "street_fias_id": "95dbf7fb-0dd4-4a04-8100-4f6c847564b5",
        "street_kladr_id": "77000000000283600",
        "street_with_type": "ул Сухонская",
        "street_type": "ул",
        "street_type_full": "улица",
        "street": "Сухонская",
        "stead_fias_id": null,
        "stead_cadnum": null,
        "stead_type": null,
        "stead_type_full": null,
        "stead": null,
        "house_fias_id": "5ee84ac0-eb9a-4b42-b814-2f5f7c27c255",
        "house_kladr_id": null,
        "house_cadnum": "77:02:0004008:1017",
        "house_flat_count": null,
        "house_type": "д",
        "house_type_full": "дом",
        "house": "11",
        "block_type": null,
        "block_type_full": null,
        "block": null,
        "entrance": null,
        "floor": null,
        "flat_fias_id": null,
        "flat_cadnum": null,
        "flat_type": null,
        "flat_type_full": null,
        "flat": null,
        "flat_area": null,
        "square_meter_price": null,
        "flat_price": null,
        "room_fias_id": null,
        "room_cadnum": null,
        "room_type": null,
        "room_type_full": null,
        "room": null,
        "postal_box": null,
        "fias_id": "5ee84ac0-eb9a-4b42-b814-2f5f7c27c255",
        "fias_code": null,
        "fias_level": "8",
        "fias_actuality_state": "0",
        "kladr_id": "77000000000283600",
        "geoname_id": "524901",
        "capital_marker": "0",
        "okato": "45280583000",
        "oktmo": "45362000",
        "tax_office": "7715",
        "tax_office_legal": "7715",
        "timezone": "UTC+3",
        "geo_lat": "55.878345",
        "geo_lon": "37.6536694",
        "beltway_hit": "IN_MKAD",
        "beltway_distance": null,
        "metro": [
          {
            "name": "Медведково",
            "line": "Калужско-Рижская",
            "distance": 1.1
          },
          {
            "name": "Бабушкинская",
            "line": "Калужско-Рижская",
            "distance": 1.2
          },
          {"name": "Свиблово", "line": "Калужско-Рижская", "distance": 2.6}
        ],
        "divisions": null,
        "qc_geo": "0",
        "qc_complete": null,
        "qc_house": null,
        "history_values": null,
        "unparsed_parts": null,
        "source": null,
        "qc": null
      }
    },
    {
      "value": "г Москва, ул Сухонская, д 11А",
      "unrestricted_value": "127642, г Москва, ул Сухонская, д 11А",
      "data": {
        "postal_code": "127642",
        "country": "Россия",
        "country_iso_code": "RU",
        "federal_district": "Центральный",
        "region_fias_id": "0c5b2444-70a0-4932-980c-b4dc0d3f02b5",
        "region_kladr_id": "7700000000000",
        "region_iso_code": "RU-MOW",
        "region_with_type": "г Москва",
        "region_type": "г",
        "region_type_full": "город",
        "region": "Москва",
        "area_fias_id": null,
        "area_kladr_id": null,
        "area_with_type": null,
        "area_type": null,
        "area_type_full": null,
        "area": null,
        "city_fias_id": "0c5b2444-70a0-4932-980c-b4dc0d3f02b5",
        "city_kladr_id": "7700000000000",
        "city_with_type": "г Москва",
        "city_type": "г",
        "city_type_full": "город",
        "city": "Москва",
        "city_area": null,
        "city_district_fias_id": null,
        "city_district_kladr_id": null,
        "city_district_with_type": null,
        "city_district_type": null,
        "city_district_type_full": null,
        "city_district": null,
        "settlement_fias_id": null,
        "settlement_kladr_id": null,
        "settlement_with_type": null,
        "settlement_type": null,
        "settlement_type_full": null,
        "settlement": null,
        "street_fias_id": "95dbf7fb-0dd4-4a04-8100-4f6c847564b5",
        "street_kladr_id": "77000000000283600",
        "street_with_type": "ул Сухонская",
        "street_type": "ул",
        "street_type_full": "улица",
        "street": "Сухонская",
        "stead_fias_id": null,
        "stead_cadnum": null,
        "stead_type": null,
        "stead_type_full": null,
        "stead": null,
        "house_fias_id": "abc31736-35c1-4443-a061-b67c183b590a",
        "house_kladr_id": null,
        "house_cadnum": "77:02:0004008:1018",
        "house_flat_count": null,
        "house_type": "д",
        "house_type_full": "дом",
        "house": "11А",
        "block_type": null,
        "block_type_full": null,
        "block": null,
        "entrance": null,
        "floor": null,
        "flat_fias_id": null,
        "flat_cadnum": null,
        "flat_type": null,
        "flat_type_full": null,
        "flat": null,
        "flat_area": null,
        "square_meter_price": null,
        "flat_price": null,
        "room_fias_id": null,
        "room_cadnum": null,
        "room_type": null,
        "room_type_full": null,
        "room": null,
        "postal_box": null,
        "fias_id": "abc31736-35c1-4443-a061-b67c183b590a",
        "fias_code": null,
        "fias_level": "8",
        "fias_actuality_state": "0",
        "kladr_id": "77000000000283600",
        "geoname_id": "524901",
        "capital_marker": "0",
        "okato": "45280583000",
        "oktmo": "45362000",
        "tax_office": "7715",
        "tax_office_legal": "7715",
        "timezone": "UTC+3",
        "geo_lat": "55.8781795",
        "geo_lon": "37.6520145",
        "beltway_hit": "IN_MKAD",
        "beltway_distance": null,
        "metro": [
          {
            "name": "Медведково",
            "line": "Калужско-Рижская",
            "distance": 1.2
          },
          {
            "name": "Бабушкинская",
            "line": "Калужско-Рижская",
            "distance": 1.2
          },
          {"name": "Свиблово", "line": "Калужско-Рижская", "distance": 2.6}
        ],
        "divisions": null,
        "qc_geo": "0",
        "qc_complete": null,
        "qc_house": null,
        "history_values": null,
        "unparsed_parts": null,
        "source": null,
        "qc": null
      }
    }
  ]
}

Только в одном городе

curl

curl https://api.adresnitsa.ru/suggestions/api/4_1/rs/suggest/address \
  -H "Authorization: Token ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{"query": "баумана", "count": 3, "locations": [{"city": "казань"}], "restrict_value": true}'

JavaScript

const res = await fetch("https://api.adresnitsa.ru/suggestions/api/4_1/rs/suggest/address", {
  method: "POST",
  headers: {
    Authorization: "Token ВАШ_КЛЮЧ",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: "баумана", count: 3, locations: [{ city: "казань" }], restrict_value: true }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.adresnitsa.ru/suggestions/api/4_1/rs/suggest/address",
    json={"query": "баумана", "count": 3, "locations": [{"city": "казань"}], "restrict_value": True},
    headers={"Authorization": "Token ВАШ_КЛЮЧ"},
    timeout=5,
)
data = res.json()

PHP

<?php
$body = json_encode(["query" => "баумана", "count" => 3, "locations" => [["city" => "казань"]], "restrict_value" => true], JSON_UNESCAPED_UNICODE);
$ctx = stream_context_create(["http" => [
    "method" => "POST",
    "header" => "Authorization: Token ВАШ_КЛЮЧ\r\n" .
        "Content-Type: application/json\r\n",
    "content" => $body,
    "ignore_errors" => true,
]]);
$data = json_decode(file_get_contents("https://api.adresnitsa.ru/suggestions/api/4_1/rs/suggest/address", false, $ctx), true);

В ответе улица Баумана в Казани и дома на ней, без «г Казань» в value: так работает restrict_value.

Адрес по GUID

curl

curl https://api.adresnitsa.ru/suggestions/api/4_1/rs/findById/address \
  -H "Authorization: Token ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{"query": "5ee84ac0-eb9a-4b42-b814-2f5f7c27c255"}'

JavaScript

const res = await fetch("https://api.adresnitsa.ru/suggestions/api/4_1/rs/findById/address", {
  method: "POST",
  headers: {
    Authorization: "Token ВАШ_КЛЮЧ",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: "5ee84ac0-eb9a-4b42-b814-2f5f7c27c255" }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.adresnitsa.ru/suggestions/api/4_1/rs/findById/address",
    json={"query": "5ee84ac0-eb9a-4b42-b814-2f5f7c27c255"},
    headers={"Authorization": "Token ВАШ_КЛЮЧ"},
    timeout=5,
)
data = res.json()

PHP

<?php
$body = json_encode(["query" => "5ee84ac0-eb9a-4b42-b814-2f5f7c27c255"], JSON_UNESCAPED_UNICODE);
$ctx = stream_context_create(["http" => [
    "method" => "POST",
    "header" => "Authorization: Token ВАШ_КЛЮЧ\r\n" .
        "Content-Type: application/json\r\n",
    "content" => $body,
    "ignore_errors" => true,
]]);
$data = json_decode(file_get_contents("https://api.adresnitsa.ru/suggestions/api/4_1/rs/findById/address", false, $ctx), true);

По координатам

curl

curl https://api.adresnitsa.ru/suggestions/api/4_1/rs/geolocate/address \
  -H "Authorization: Token ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{"lat": 55.87834, "lon": 37.65367, "radius_meters": 50, "count": 1}'

JavaScript

const res = await fetch("https://api.adresnitsa.ru/suggestions/api/4_1/rs/geolocate/address", {
  method: "POST",
  headers: {
    Authorization: "Token ВАШ_КЛЮЧ",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ lat: 55.87834, lon: 37.65367, radius_meters: 50, count: 1 }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.adresnitsa.ru/suggestions/api/4_1/rs/geolocate/address",
    json={"lat": 55.87834, "lon": 37.65367, "radius_meters": 50, "count": 1},
    headers={"Authorization": "Token ВАШ_КЛЮЧ"},
    timeout=5,
)
data = res.json()

PHP

<?php
$body = json_encode(["lat" => 55.87834, "lon" => 37.65367, "radius_meters" => 50, "count" => 1], JSON_UNESCAPED_UNICODE);
$ctx = stream_context_create(["http" => [
    "method" => "POST",
    "header" => "Authorization: Token ВАШ_КЛЮЧ\r\n" .
        "Content-Type: application/json\r\n",
    "content" => $body,
    "ignore_errors" => true,
]]);
$data = json_decode(file_get_contents("https://api.adresnitsa.ru/suggestions/api/4_1/rs/geolocate/address", false, $ctx), true);

Чем отличается

В data всегда все 98 ключей в привычном порядке. Где у нас нет значения, там null.
Все поля — в каждом тарифе: координаты, метро, МКАД и кадастровый номер приходят и в бесплатном.
Ошибки — в привычном виде {"family", "reason", "message"} и с привычными статусами (ошибки совместимого режима).
Лимиты и счёт запросов — общие с своим API.

Ответ401 Unauthorizedданные 2026.01.02 v.219

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
WWW-Authenticate: Token
X-Data-Version: 2026.01.02 v.219

{
  "family": "CLIENT_ERROR",
  "reason": "Unauthorized",
  "message": "an API key is needed: Authorization: Token <key>"
}