API Адреса

Работа с адресами

Справочник населенных пунктов Украины

Метод «getSettlements» работает в модели «AddressGeneral», этот позволяет загрузить справочников городов Украины (на Украинском или Русском), в которые осуществляется доставка груза компанией «Новая Почта».
Стоит учитывать, что метод «getSettlements» для каждого населенного пункта возвращает область, и район. Метод отдает не более 150 записей на страницу. Для просмотра более 150 записей, необходимо использовать параметр "Page": "1",

Также в методе доступен поиск по строке, для него нужно указать параметр FindByString. Важно! Поиск возможен только на Украинском языке. Пример:
"methodProperties": {
"FindByString": "Бровари"
}
Необходимо сохранять копию справочников на стороне клиента и поддерживать ее в актуальном состоянии.
Рекомендуется проводить обновление справочников раз в месяц.

Новый параметр "Warehouse": "1 или 0" позволит отобразить только те населенные пункты в которых есть отделения "Нова пошта"

URL для входа https://api.novaposhta.ua/v2.0/{format}/ [json or xml]/
Формат, обязательно, должен указываться нижним регистром (маленькими буквами), например https://api.novaposhta.ua/v2.0/json/


Доступность: Требует использования API-ключа.

Try it

URL-адрес запроса

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

string

Форматы JSON, XML

Заголовки запросов

(дополнительный)
string
Тип формата текста, отправляемого в API.

Текст запроса

Параметр Тип данных Описание
apiKey* string[36] Ваш ключ API 2.0
modelName* string Имя модели
calledMethod* string Имя вызываемого метода
methodProperties   Свойства метода
Ref string[36] Идентификатор адреса
RegionRef string[36] Фильтр по идентификатору района
FindByString string[36] Поиск по строкам Украинский либо Русский язык
Warehouse string[36] Фильтр наличия отделений
Page string[36] Номер страницы
* Обозначение обязательного параметра 

{
    "modelName": "AddressGeneral",
    "calledMethod": "getSettlements",
    "methodProperties": {
        "AreaRef": "dcaadb64-4b33-11e4-ab6d-005056801329",
        "Ref": "0e451e40-4b3a-11e4-ab6d-005056801329",
        "RegionRef": "e4ade6ea-4b33-11e4-ab6d-005056801329",
        "Page": "1"
    },
    "apiKey": "[ВАШ КЛЮЧ]"
}

<?xml version="1.0" encoding="UTF-8" ?>
<root>
    <modelName>AddressGeneral</modelName>
    <calledMethod>getSettlements</calledMethod>
    <methodProperties>
        <AreaRef>dcaadb64-4b33-11e4-ab6d-005056801329</AreaRef>
        <Ref>0e451e40-4b3a-11e4-ab6d-005056801329</Ref>
        <RegionRef>e4ade6ea-4b33-11e4-ab6d-005056801329</RegionRef>
        <Page>1</Page>
    </methodProperties>
    <apiKey>[ВАШ КЛЮЧ]</apiKey>
</root>

Ответ 200

Всегда возвращает код 200 даже при логических ошибках.


Тело ответа на запрос

Параметр Тип данных Описание
Ref string[36] Идентификатор адреса
SettlementType string[36] Тип населенного пункта (Село, ПГТ и т.д.)
Description string[50] Адрес на Украинском языке
DescriptionRu string[50] Адрес на русском языке
Area string[36] Обозначение области
SettlementTypeDescription string[36] Тип населённого пункта
SettlementTypeDescriptionRu string[36] Тип населённого пункта<
Region string[50] Код населенного пункта
RegionsDescription string[50] Область
RegionsDescriptionRu string[50] Область
Index int[10] Индекс
IndexCOATSU1 int[10] Диапазон индексов КОАТУУ
Delivery1-Delivery7 string[50] Наличие доставки отправления в днях недели
Warehouse int[50] Наличие отделений 

{
  "success": true,
  "data": [
    {
      "Ref": "e718a680-4b33-11e4-ab6d-005056801329",
      "SettlementType": "563ced10-f210-11e3-8c4a-0050568002cf",
      "Latitude": "50.450418000000000",
      "Longitude": "30.523541000000000",
      "Description": "Київ",
      "DescriptionRu": "Киев",
      "SettlementTypeDescription": "місто",
      "SettlementTypeDescriptionRu": "город",
      "Region": "",
      "RegionsDescription": "",
      "RegionsDescriptionRu": "",
      "Area": "dcaadb64-4b33-11e4-ab6d-005056801329",
      "AreaDescription": "Київська область",
      "AreaDescriptionRu": "Киевская область",
      "Index1": "01001",
      "Index2": "04655",
      "IndexCOATSU1": "3200000000",
      "Delivery1": "1",
      "Delivery2": "1",
      "Delivery3": "1",
      "Delivery4": "1",
      "Delivery5": "1",
      "Delivery6": "1",
      "Delivery7": "0",
      "Warehouse": "1",
      "Conglomerates": [
        "d4771ed0-4fb7-11e4-91b8-2f592fe1dcac",
        "f86b75e9-42f4-11e4-91b8-2f592fe1dcac"
      ]
    }
  ],
  "errors": [],
  "warnings": [],
  "info": {
    "totalCount": 1
  },
  "messageCodes": [],
  "errorCodes": [],
  "warningCodes": [],
  "infoCodes": []
}
<?xml version="1.0" encoding="UTF-8"?>
<root>
   <data>
      <element>
         <Area>dcaadf02-4b33-11e4-ab6d-005056801329</Area>
         <AreaDescription>Полтавська область</AreaDescription>
         <AreaDescriptionRu>Полтавская область</AreaDescriptionRu>
         <Delivery1 />
         <Delivery2 />
         <Delivery3 />
         <Delivery4 />
         <Delivery5 />
         <Delivery6 />
         <Delivery7 />
         <Description>Абазівка</Description>
         <DescriptionRu>Абазовка</DescriptionRu>
         <Index1>38715</Index1>
         <Index2>38715</Index2>
         <IndexCOATSU1></3200000000>
         <Latitude>0.000000000000000</Latitude>
         <Longitude>0.000000000000000</Longitude>
         <Ref>0e451e40-4b3a-11e4-ab6d-005056801329</Ref>
         <Region>e4ade6ea-4b33-11e4-ab6d-005056801329</Region>
         <RegionsDescription>Полтавський р-н</RegionsDescription>
         <RegionsDescriptionRu>Полтавский р-н</RegionsDescriptionRu>
         <SettlementType>563ced13-f210-11e3-8c4a-0050568002cf</SettlementType>
         <SettlementTypeDescription>село</SettlementTypeDescription>
         <SettlementTypeDescriptionRu>село</SettlementTypeDescriptionRu>
      </element>
   </data>
   <errors />
   <info />
   <success>true</success>
   <warnings />
</root>