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

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

SOAP Endpoint: GetReferenceData Обновлено: 2026-05-25

Endpoint: GetReferenceData
SOAP-метод: Geography
Группа: GetReferenceData
Создано: 16.04.2026 · Обновлено: 25.05.2026

Описание

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

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

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

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

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

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

название;
индекс;
код ФИАС.

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

Параметр	Тип	Обязательно	Описание
login	string	да	логин
password	string	да	пароль
parameters	element	да	список параметров

Описание параметра parameters

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

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

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

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

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

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

xml

<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) страны, к которой относится объект. Присутствует для всех объектов, кроме стран верхнего уровня

Пример запроса (XML Request)

xml

<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>

Пример ответа (XML Response)

xml

<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>

Смежные методы

AvailableDeliveryDates

Функция позволяет получить информацию о возможных датах доставки груза.

BaseUnitsOfMeasurement

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

CargoStates

Функция позволяет получить список доступных состояний грузов.