Работа с сущностью "Населенный пункт (locality)"

Изменено Пн, 20 Июн, 2022 на 4:00 PM

Получить информацию о населенном пункте

Route: https://cdek.orderadmin.ru/api/locations/localities/<locality_id>
Method: GET
Headers: Accept: application/json
Authorization: basic

Пример запроса (PHP):

<?php

$url = 'https://cdek.orderadmin.ru/api/locations/localities/62216';
$headers = [
    'Accept: application/json'
];
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, '<user>:<password>');
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($data);

Пример запроса (curl):

curl -X GET \
-u "<user>:<password>" \
-H "Accept: application/json" \
"https://cdek.orderadmin.ru/api/locations/localities/62216"

Пример запроса (Python):

import requests

api_url = 'https://cdek.orderadmin.ru/api/locations/localities/62216'
result = requests.get(api_url, auth=(
    '<user>', 
    '<password>'
))
print(result.json())

Пример ответа сервера:

{
    "id": 62216,
    "state": "active",
    "name": "Москва",
    "type": "город",
    "geo": "SRID=4326;POINT(38.485552 55.427729)",
    "settings": {
        "geo": {
            "lat": "55.75396",
            "lng": "37.620393"
        },
        "timezone": {
            "offset": 3,
            "timezone": "Europe/Moscow"
        }
    },
    "extId": "0c5b2444-70a0-4932-980c-b4dc0d3f02b5",
    "postcode": "101000",
    "_embedded": {
        "country": {
            "id": 28,
            "state": "active",
            "code": "RU",
            "name": "Россия",
            "nativeLocale": "ru_RU",
            "type": "fias"
        },
        "area": {
            "id": 2165,
            "state": "active",
            "name": "Московская Область",
            "nativeLocale": "ru_ru",
            "extId": "29251dcf-00a1-4e34-98d4-5c47484a36d4",
            "postcode": null
        }
    },
    "_links": {
        "self": {
            "href": "https://cdek.orderadmin.ru/api/locations/localities/62216"
        }
    }
}

Описание полей ответа:

Параметр	Описание
name	Название
type	тип населенного пункта (город, село, деревня и т.д.)
settings.timezone	Часовой пояс
_embedded.country	Информация о стране
_embedded.area	Информация об области

Получить список населенных пунктов

Route: https://cdek.orderadmin.ru/api/locations/localities
Method: GET
Headers: Accept: application/json
Authorization: basic

Пример запроса (PHP):

<?php

$url = 'https://cdek.orderadmin.ru/api/locations/localities';
$headers = [
    'Accept: application/json'
];
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, '<user>:<password>');
$data = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($data);

Пример запроса (curl):

curl -X GET \
-u "<user>:<password>" \
-H "Accept: application/json" \
"https://cdek.orderadmin.ru/api/locations/localities"

Пример запроса (Python):

import requests

api_url = 'https://cdek.orderadmin.ru/api/locations/localities'
result = requests.get(api_url, auth=(
    '<user>', 
    '<password>'
))
print(result.json())

Пример ответа сервера:

{
    "_links": {
        "self": {
            "href": "https://cdek.orderadmin.ru/api/locations/localities?page=1"
        },
        "first": {
            "href": "https://cdek.orderadmin.ru/api/locations/localities"
        },
        "last": {
            "href": "https://cdek.orderadmin.ru/api/locations/localities?page=11614"
        },
        "next": {
            "href": "https://cdek.orderadmin.ru/api/locations/localities?page=2"
        }
    },
    "_embedded": {
        "localities": [
            /* Массив объектов locality */
        ]
    },
    "page_count": 11614,
    "page_size": 25,
    "total_items": 290337,
    "page": 1
}

Поиск по атрибутам

Точное совпадение названия:

https://cdek.orderadmin.ru/api/locations/localities?filter[0][type]=eq&filter[0][field]=name&filter[0][value]=Москва

Название плюс тип:

https://cdek.orderadmin.ru/api/locations/localities?filter[0][type]=eq&filter[0][field]=name&filter[0][value]=Москва&filter[1][type]=eq&filter[1][field]=type&filter[1][value]=город

Частичное совпадение названия:

https://cdek.orderadmin.ru/api/locations/localities?filter[0][type]=ilike&filter[0][field]=name&filter[0][value]=Москв%

Частичное совпадение названия плюс код страны:

https://cdek.orderadmin.ru/api/locations/localities?filter[0][type]=ilike&filter[0][field]=name&filter[0][value]=Москв%&filter[1][type]=eq&filter[1][field]=country&filter[1][value]=28

Поиск по почтовому индексу

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

https://cdek.orderadmin.ru/api/delivery-services/postcodes?filter[0][type]=eq&filter[0][field]=extId&filter[0][value]=<почтовый_индекс>

Пример ответа сервера:

{
    "_links": {
        "self": {
            "href": "https://cdek.orderadmin.ru/api/delivery-services/postcodes?filter%5B0%5D%5Btype%5D=eq&filter%5B0%5D%5Bfield%5D=extId&filter%5B0%5D%5Bvalue%5D=103274&page=1"
        },
        "first": {
            "href": "https://cdek.orderadmin.ru/api/delivery-services/postcodes?filter%5B0%5D%5Btype%5D=eq&filter%5B0%5D%5Bfield%5D=extId&filter%5B0%5D%5Bvalue%5D=103274"
        },
        "last": {
            "href": "https://cdek.orderadmin.ru/api/delivery-services/postcodes?filter%5B0%5D%5Btype%5D=eq&filter%5B0%5D%5Bfield%5D=extId&filter%5B0%5D%5Bvalue%5D=103274&page=1"
        }
    },
    "_embedded": {
        "postcodes": [
            {
                "extId": "103274",
                "geo": null,
                "id": 31222,
                "state": "active",
                "_embedded": {
                    "country": {
                        "id": 28,
                        "state": "active",
                        "code": "RU",
                        "name": "Россия",
                        "nativeLocale": "ru_RU"
                    },
                    "locality": {
                        "id": 62216,
                        "state": "active",
                        "name": "Москва",
                        "type": "город",
                        "geo": "SRID=4326;POINT(38.485552 55.427729)",
                        "settings": {
                            "geo": {
                                "lat": "55.75396",
                                "lng": "37.620393"
                            },
                            "timezone": {
                                "offset": 3,
                                "timezone": "Europe/Moscow"
                            }
                        },
                        "extId": "0c5b2444-70a0-4932-980c-b4dc0d3f02b5",
                        "postcode": "101000"
                    }
                },
                "_links": {
                    "self": {
                        "href": "https://cdek.orderadmin.ru/api/delivery-services/postcodes/31222"
                    }
                }
            }
        ]
    },
    "page_count": 1,
    "page_size": 50,
    "total_items": 1,
    "page": 1
}

Описание полей ответа:

Параметр	Описание
extId	Почтовый индекс
_embedded.country	Информация о стране
_embedded.locality	Информация о населенном пункте