Поиск региона

Описание

GET /regions

Возвращает информацию о регионе, удовлетворяющем заданным в запросе условиям поиска.

Если найдено несколько регионов, удовлетворяющих условиям поиска, возвращается информация по каждому найденному региону (но не более десяти регионов) для возможности определения нужного региона по родительским регионам.

Примечание. Метод доступен начиная с версии 1.2 партнерского API Яндекс.Маркета.

URL ресурса:

https://api.partner.market.yandex.ru/v2/regions.[format]?name={regionName}

Входные данные

Параметр

Тип

Значение

Обязательные

name

String

Название региона.

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

Выходные данные

Структура выходных данных приведена ниже. Порядок следования параметров не гарантируется.

<response>
  <regions>
    <region id="{int64}" name="{string}" type="{enum}">
      <parent id="{int64}" name="{string}" type="{enum}">
        ...
      </parent>
    </region>
    ...
  </regions>
</response>

Описание параметров:

Параметр для формата XML

Параметр для формата JSON

Тип

Значение

response

Ответ.

Параметр выводится только для формата XML.

Параметры, вложенные в response

regions regions

Список регионов, удовлетворяющих условиям поиска.

Параметры, вложенные в regions

region

Информация о регионе.

Параметр выводится только для формата XML.

Параметры, вложенные в region / regions

id id Int64

Идентификатор региона.

Для формата XML является атрибутом параметра region.

name name String

Название региона.

Для формата XML является атрибутом параметра region.

type type Enum

Тип региона.

Возможные значения:

  • AREA — область.

  • CITY — крупный город.

  • CONTINENT — континент.

  • COUNTRY — страна.

  • DISCTRICT — район города.

  • MONORAIL_STATION — станция монорельса.

  • OVERSEAS_TERRITORY — отдельная территория какого-либо государства, расположенная в другой части света (например, Ангилья, Гренландия, Бермудские острова и т. д.).

  • REGION — регион.

  • REPUBLIC — субъект федерации.

  • REPUBLIC_AREA — район субъекта федерации.

  • SECONDARY_DISTRICT — район города второго уровня (например, для ВАО Москвы районами второго уровня являются Измайлово, Новокосино, Перово и т. д.).

  • SETTLEMENT — поселение.

  • SUBURB — пригород.

  • SUBWAY_STATION — станция метро.

  • TOWN — город.

  • UNKNOWN — неизвестный регион.

Для формата XML является атрибутом параметра region.

parent parent

Информация о родительском регионе.

Указываются родительские регионы до уровня страны.

Параметры, вложенные в parent

id id Int64

Идентификатор родительского региона.

Для формата XML является атрибутом параметра parent.

name name String

Название родительского региона.

Для формата XML является атрибутом параметра parent.

type type Enum

Тип родительского региона.

Возможные значения:

  • AREA — область.

  • CITY — крупный город.

  • CONTINENT — континент.

  • COUNTRY — страна.

  • DISCTRICT — район города.

  • MONORAIL_STATION — станция монорельса.

  • OVERSEAS_TERRITORY — отдельная территория какого-либо государства, расположенная в другой части света (например, Ангилья, Гренландия, Бермудские острова и т. д.).

  • REGION — регион.

  • REPUBLIC — субъект федерации.

  • REPUBLIC_AREA — район субъекта федерации.

  • SECONDARY_DISTRICT — район города второго уровня (например, для ВАО Москвы районами второго уровня являются Измайлово, Новокосино, Перово и т. д.).

  • SETTLEMENT — поселение.

  • SUBURB — пригород.

  • SUBWAY_STATION — станция метро.

  • TOWN — город.

  • UNKNOWN — неизвестный регион.

Для формата XML является атрибутом параметра parent.

parent parent

Рекурсивно вложенный элемент для указания родительских регионов более высокого уровня.

Описание ошибок

В случае ошибки сервер возвращает HTTP-код ответа и краткое описание ошибки.

Ограничения

Для методов GET /regions, GET /regions/{regionId} и GET /regions/{regionId}/children действует групповое ресурсное ограничение. Ограничение вводится на суммарное количество регионов, информация о которых запрошена при помощи этих методов (не более 100 000 регионов).

Объем запросов к ресурсу, который возможно выполнить в течение суток, зависит от суммарного количества регионов.

Примеры

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

curl -i -H 'Content-Type: application/xml' 'https://api.partner.market.yandex.ru/v2/regions.xml?name=Ивановка'

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

HTTP/1.1 200 OK
Date: Wed, 25 Jan 2017 00:42:42 GMT
Content-Type: application/xml;charset=utf-8
...

<response>
  <regions>
    <region id="11380" name="Ивановка" type="TOWN">
      <parent id="100295" name="Ивановский район" type="REPUBLIC_AREA">
        <parent id="11375" name="Амурская область" type="REPUBLIC">
          <parent id="73" name="Дальневосточный федеральный округ" type="AREA">
            <parent id="225" name="Россия" type="COUNTRY"/>
          </parent>
        </parent>
      </parent>
    </region>
    <region id="28630" name="Ивановка" type="TOWN">
      <parent id="24533" name="Ивановский район" type="REPUBLIC_AREA">
        <parent id="20548" name="Одесская область" type="REPUBLIC">
          <parent id="20527" name="Юг" type="REGION">
            <parent id="187" name="Украина" type="COUNTRY"/>
          </parent>
        </parent>
      </parent>
    </region>
  </regions>
</response>