Try it — Geography
SOAP Request

Отредактируйте параметры запроса и нажмите Выполнить для отправки запроса на сервер

GetReferenceData: Geography — География

  • Создано 16.04.2026
  • Обновлено 25.05.2026
  • Endpoint: GetReferenceData
  • Soap-method: Geography
Описание

Функция предназначена для получения списка географических объектов. Полученные данные используются при последующих вызовах других функций веб-сервиса.

Справочник имеет иерархическую структуру (дерево):

  • Верхний уровень — города и населённые пункты;
  • Нижний уровень — страны.

Режимы работы функции:

1.  Запрос по ветви и уровню. Допускается получение данных только для одной ветви дерева и только для одного уровня иерархии.

2. Запрос по атрибутам объекта. Поддерживается поиск географического объекта по следующим критериям:

  • название;
  • индекс;
  • код ФИАС.
Параметры запроса
Параметр Тип Обязательно Описание
login string логин
password string пароль
parameters element список параметров
Описание параметра parameters

Параметр parameters содержит настройки запроса в виде иерархической структуры, соответствующей XML-представлению.

Он должен включать:

Key: строка со значением parameters (обязательное);

List: непустой массив элементов, каждый из которых представляет отдельный параметр и сам является структурой с тремя полями:

  • Key: имя параметра (например, Reference);
  • Value: значение параметра указывающая на то какой parameters  описывается;
  • ValueType: тип значения — строка, указывающая тип Value(string, int и т.д.).

Пример одного элемента из List:

<car:List>
   <car:Key>Reference</car:Key>
   <car:Value>Geography</car:Value>
   <car:ValueType>string</car:ValueType>
</car:List>

Каждый такой элемент — независимый узел внутри parameters. Если List отсутствует или пуст — запрос отклоняется.

Иерархия структуры parameters:

parameters → List (массив) → каждый элемент List → Key, Value, ValueType.

Параметр Тип Обязательно Описание
Reference string Имя справочника, должно быть равно «Geography»
Search string Название объекта географии для поиска.
1. Поиск по названию
Формат: произвольная строка
Требование: точное соответствие названию объекта в базе «Карго»
Особенность: при использовании этого формата параметр InGroup игнорируется
2. Поиск по коду ФИАС
Формат: fias-<код ФИАС>
Пример: fias-12345678-9012345678
3. Поиск по почтовому индексу
Формат: postcode-[код страны]<индекс>
postcode - обязательный префикс
код страны - необязательный; допустимые форматы: цифровой, Альфа-2, Альфа-3. По умолчанию — Россия
<индекс> - обязательный; почтовый индекс для поиска
Пример:
postcode-KZ-A00A0A0 - поиск по индексу в Казахстане
postcode-RU-990500 - поиск по индексу в России (явное указание страны)
postcode-990500 - поиск по индексу в России (без указания страны); может возвращать неточные результаты
InGroup string Имя группы, в которой выполняется выборка объектов географии; представляет собой GUID элемента географии. Если параметр не указан, или передана пустая строка, то выборка выполняется в корне географии, среди списка стран
Возвращаемые параметры

Параметр Element в ответе содержит информацию о видах грузов.

Он включает элементы справочника:

Key: строка со значением Geography;

List: непустой массив элементов, каждый из которых содержит информацию о конкретном географическом объекте.

Каждый географический объект в списке List представлен набором полей следующей структуры:

  • Key: уникальный идентификатор (GUID) географического объекта (например, cf862f56-442d-11dc-9497-0015170f8c09)
  • Value: наименование географического объекта (например, Москва г);
  • ValueType: тип значения — строка, указывающая тип Value (string, dateTime и т.п.);
  • Fields: набор дополнительных атрибутов объекта.

Структура ответа иерархична:

Element → Key + List (массив) → каждый элемент List → Key + Value +ValueType +Fields→ каждый элемент Fields  → Key, Value, ValueType.

Если во время запроса произошла ошибка, информация о ней будет отражена в свойстве Properties (см. метод GetReferenceData: ErrorCodes — Коды ошибок). 

Параметр Тип Обязательно Описание
Key string Уникальный номер элемента справочника в формате GUID (Globally Unique Identifier)
Value string Наименование географического объекта
Fields element Другие свойства элемента справочника
Возвращаемые параметры Fields

Каждый атрибут Fields имеет структуру:

  • Key: идентификатор атрибута (название поля) (например,  Default);
  • Value: значение поля (тип определяется атрибутом);
  • ValueType: тип значения — строка, указывающая тип Value (string, boolean и т.п.).
Параметр Тип Обязательно Описание
Default boolean Признак объекта, используемого по умолчанию
Parent string GUID (Globally Unique Identifier) родителя данного объекта. Если родителя нет, то возвращается
пустая строка
ParentName string Наименование родителя данного объекта. Если родителя нет, то возвращается пустая строка
Locked boolean Признак блокировки географии для выбора населенного пункта
Settlement boolean Признак того, что данный объект - населённый пункт
State boolean Признак того, что данный объект - страна
Type float Числовой код, определяющий тип географического объекта (см. описание метода GetReferenceData: TypesOfGeographicObjects — Виды объектов географии)
KLADR string Код по классификатору КЛАДР (ведомственный классификатор адресов ФНС России)
AltCode string Альтернативный код (например, IATA-код). Для городов может содержать IATA-код (трёхбуквенный код аэропорта/города). Для других объектов — внешние системные идентификаторы
FIAS string Уникальный идентификатор объекта в Федеральной информационной адресной системе (ФИАС). Используется для точной идентификации адресных объектов
PrimaryState boolean Признак, является ли регион/штат основным (например, для стран с несколькими столицами или административными центрами)
HaveDependentObjects boolean Признак наличия дочерних географических объектов (например, у страны есть регионы)
CountryCode string Уникальный идентификатор (GUID) страны, к которой относится объект. Присутствует для всех объектов, кроме стран верхнего уровня
Примеры запроса/ответа 
<soap:Envelope
  xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
  xmlns:car="http://www.cargo3.ru">
  <soap:Header/>
  <soap:Body>
    <car:GetReferenceData>
      <car:login>test</car:login>
      <car:password>2016</car:password>
      <car:parameters>
        <car:Key>parameters</car:Key>
        <car:List>
          <car:Key>Reference</car:Key>
          <car:Value>Geography</car:Value>
          <car:ValueType>string</car:ValueType>
        </car:List>
        <car:List>
          <car:Key>Search</car:Key>
          <car:Value>Москва г</car:Value>
          <car:ValueType>string</car:ValueType>
        </car:List>
      </car:parameters>
    </car:GetReferenceData>
  </soap:Body>
</soap:Envelope>
<soap:Envelope
  xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
  <soap:Body>
    <m:GetReferenceDataResponse
      xmlns:m="http://www.cargo3.ru">
      <m:return
        xmlns:xs="http://www.w3.org/2001/XMLSchema"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <m:Key>Geography</m:Key>
        <m:List>
          <m:Key>cf862f56-442d-11dc-9497-0015170f8c09</m:Key>
          <m:Value xsi:type="xs:string">Москва г</m:Value>
          <m:ValueType>string</m:ValueType>
          <m:Fields>
            <m:Key>Default</m:Key>
            <m:Value xsi:type="xs:boolean">true</m:Value>
            <m:ValueType>boolean</m:ValueType>
          </m:Fields>
          <m:Fields>
            <m:Key>Parent</m:Key>
            <m:Value xsi:type="xs:string">f2cd6487-4422-11dc-9497-0015170f8c09</m:Value>
            <m:ValueType>string</m:ValueType>
          </m:Fields>
          <m:Fields>
            <m:Key>ParentName</m:Key>
            <m:Value xsi:type="xs:string">РОССИЯ</m:Value>
            <m:ValueType>string</m:ValueType>
          </m:Fields>
          <m:Fields>
            <m:Key>Locked</m:Key>
            <m:Value xsi:type="xs:boolean">false</m:Value>
            <m:ValueType>boolean</m:ValueType>
          </m:Fields>
          <m:Fields>
            <m:Key>Settlement</m:Key>
            <m:Value xsi:type="xs:boolean">true</m:Value>
            <m:ValueType>boolean</m:ValueType>
          </m:Fields>
          <m:Fields>
            <m:Key>State</m:Key>
            <m:Value xsi:type="xs:boolean">false</m:Value>
            <m:ValueType>boolean</m:ValueType>
          </m:Fields>
          <m:Fields>
            <m:Key>Type</m:Key>
            <m:Value xsi:type="xs:string">3</m:Value>
            <m:ValueType>string</m:ValueType>
          </m:Fields>
          <m:Fields>
            <m:Key>KLADR</m:Key>
            <m:Value xsi:type="xs:string">77000000000</m:Value>
            <m:ValueType>string</m:ValueType>
          </m:Fields>
          <m:Fields>
            <m:Key>AltCode</m:Key>
            <m:Value xsi:type="xs:string">MOW</m:Value>
            <m:ValueType>string</m:ValueType>
          </m:Fields>
          <m:Fields>
            <m:Key>FIAS</m:Key>
            <m:Value xsi:type="xs:string">0c5b2444-70a0-4932-980c-b4dc0d3f02b5</m:Value>
            <m:ValueType>string</m:ValueType>
          </m:Fields>
          <m:Fields>
            <m:Key>PrimaryState</m:Key>
            <m:Value xsi:type="xs:boolean">false</m:Value>
            <m:ValueType>boolean</m:ValueType>
          </m:Fields>
          <m:Fields>
            <m:Key>HaveDependentObjects</m:Key>
            <m:Value xsi:type="xs:boolean">true</m:Value>
            <m:ValueType>boolean</m:ValueType>
          </m:Fields>
          <m:Fields>
            <m:Key>CountryCode</m:Key>
            <m:Value xsi:type="xs:string">4e127564-d74f-4dd9-bced-0327f0f4e061</m:Value>
            <m:ValueType>string</m:ValueType>
          </m:Fields>
        </m:List>
      </m:return>
    </m:GetReferenceDataResponse>
  </soap:Body>
</soap:Envelope>