Загрузка данных по API | 2ГИС Про | 2GIS Documentation
2ГИС Про
Карты
Поиск
Навигация
2ГИС Про
2ГИС Линза
On‑Premise
Личный кабинет
ру
en

Загрузка данных по API

Вы можете загружать данные из внешних источников в сервис 2ГИС Про с помощью API. В динамический набор данных можно подгружать данные неограниченное количество раз, поэтому этот способ подходит для работы с изменчивыми по своей природе данными.

Возможность загрузки данных зависит от тарифа. Загрузить данные можно для любой территории, но детальная карта будет доступна только в странах, для которых в 2ГИС есть системные данные: см. список стран.

Примечание

Через API вы можете загружать данные только в отдельные наборы данных, созданные по инструкции ниже. Нельзя загрузить данные в системные наборы данных и в наборы, загруженные как файл.

Чтобы загрузить данные по API и работать с ними:

  1. Создайте пустой набор, в который будут подгружаться данные.
  2. Загрузите порцию данных в набор. Вы можете отправлять данные в набор любое количество раз в рамках лимитов.
  3. Создайте слой с выборкой данных.

1. Создайте набор для загрузки данных

  1. Создайте пустой набор, в который вы будете подгружать данные:

    1. Отправьте POST-запрос к /dynamic_asset:

      https://pro-api.2gis.ru/dynamic_asset

      Для авторизации используйте Bearer-токен.

      Как получить Bearer-токен
      1. Откройте интерфейс 2ГИС Про и Инструменты разработчика (клавиша F12).
      2. В 2ГИС Про нажмите значок Профиль в левом нижнем углу, чтобы открыть вкладку профиля.
      3. В панели Инструментов разработчика во вкладке Сеть нажмите на появившуюся строку user?include_permissions=true.
      4. В открывшейся таблице в блоке Заголовки запросов найдите строку Authorization и скопируйте символы после Bearer. Используйте эти символы как Bearer-токен для авторизации.

    2. В теле запроса передайте необходимые параметры в формате JSON:

      • geometry_dimension: тип геометрии (точка, линия, полигон). Обязательный параметр.
      • name: имя набора данных. Обязательный параметр.
      • description: описание набора данных.
      • attribute_groups: список атрибутов данных. Вы можете указать не более 100 атрибутов для каждого типа.
      • filters: настройки фильтров данных по указанным атрибутам: тип UI-элемента, список значений и т. д. Фильтры будут отображаться в интерфейсе при работе с набором данных.

      Более подробную информацию о параметрах см. в Справочнике API.

      Пример тела запроса 
      {
    "geometry_dimension": "polygon",
    "name": "Машины на карте города",
    "description": "Показывает позиции автомобилей на карте",
    "attribute_groups": [
        {
            "name": "Main features",
            "attributes": [
                {
                    "id": "Model",
                    "type": "string",
                    "caption": "Модель"
                },
                {
                    "id": "Year",
                    "type": "number",
                    "caption": "Год выпуска"
                }
            ]
        }
    ],
    "filters": [
        {
            "attribute_id": "Model",
            "control_type": "check_box_list",
            "items": [
                {
                    "value": "Mercedes Benz S600",
                    "caption": "Mercedes Benz S600"
                },
                {
                    "value": "Citroen C3",
                    "caption": "Citroen C3"
                }
            ]
        },
        {
            "attribute_id": "Year",
            "control_type": "range",
            "min": 1969,
            "max": 2022
        }
    ]
}

    В случае успешного выполнения запроса вернётся ответ с ID созданного набора данных (поле asset_id) и токеном доступа для авторизации (поле access_token). Сохраните эти значения.

  2. Откройте 2ГИС Про и обновите страницу. Созданный набор появится в списке загруженных данных.

    Примечание

    Создание набора данных может занять некоторое время. Если набор не появился в интерфейсе сразу, попробуйте обновить страницу позже.

    Новый динамический набор данных

    Чтобы увидеть настроенные фильтры, откройте набор данных и выберите территорию. Пока в набор не загружены данные, результаты будут пустыми.

    Фильтры динамического набора данных

2. Загрузите данные в набор

Чтобы загрузить в набор порцию данных:

  1. Отправьте PUT-запрос к /dynamic_asset:

    https://pro-api.2gis.ru/dynamic_asset/{assetId}/data

    Для отправки запроса используйте данные, которые вы получили при создании набора данных:

    • ID набора данных (assetId). Также вы можете скопировать ID в 2ГИС Про: перейдите на вкладку Данные, в карточке нужного набора данных нажмите значок Меню набора данных и выберите Скопировать ID.
    • Токен доступа для авторизации (access_token). Также вы можете скопировать токен в 2ГИС Про: нажмите значок Профиль в левом нижнем углу, перейдите в раздел Токены и скопируйте значение в поле Токен для работы с динамическими наборами данных.

  2. В теле запроса передайте данные в формате GeoJSON:

    • type: тип объекта GeoJSON.

    • features: параметры объекта:

      • type: тип объекта GeoJSON.

      • geometry: геометрия объекта в формате JSON.

      • id: идентификатор объекта.

      • properties: свойства объекта по схеме атрибутов данных, заданных при создании набора.

        Если в свойствах объекта имена или значения атрибутов отличаются от заданных при создании набора данных, то все новые значения будут отображены в карточке объекта, но не попадут в настройки фильтров. Чтобы обновить фильтры, отправьте запрос на изменение параметров набора данных.

    Более подробную информацию о параметрах см. в Справочнике API.

    Пример тела запроса 
    {
    "type": "FeatureCollection",
    "features": [
        {
            "id": "1",
            "type": "Feature",
            "geometry": {
                "type": "Polygon",
                "coordinates": [
                    [
                        [37.67340873626523, 55.689291576019315],
                        [37.67340873626523, 55.68384205945338],
                        [37.68043927275957, 55.68384205945338],
                        [37.68043927275957, 55.689291576019315],
                        [37.67340873626523, 55.689291576019315]
                    ]
                ]
            },
            "properties": {
                "Model": "Citroen C3",
                "Year": 2002
            }
        }
    ]
}

  3. Откройте 2ГИС Про и обновите страницу. Выберите нужный набор данных. Загруженные данные отобразятся на карте.

    Примечание

    Загрузка данных обычно занимает около минуты. Если данные не появились сразу, попробуйте обновить страницу позже.

    Динамический набор с загруженными данными

В дальнейшем вы сможете загружать данные в созданный набор по API. Работать с набором данных можно только через API: см. инструкцию Операции с наборами данных.

3. Создайте слой

Чтобы сохранить отфильтрованную выборку и настроить ее визуализацию (например, в виде тепловой карты), создайте слой.

  1. Перейдите на вкладку Главная или Данные.

  2. Выберите набор загруженных данных.

  3. На вкладке Фильтры выберите Территорию.

  4. Если загруженные данные содержат геометрии в виде линий или полигонов, вверху вкладки Фильтры выберите способ отображения данных:

    • Точки: в виде точек-центроидов (центров геометрии объектов);
    • Геометрии: в виде реальных геометрий данных (линий или полигонов).

  5. Настройте остальные параметры фильтров при необходимости.

  6. Нажмите Создать слой.

    Если в проекте еще нет дашбордов, будет создан первый дашборд, на который автоматически добавится слой с данными.

  7. Если в проекте есть дашборд, в диалоговом окне укажите куда добавить слой:

    • Выберите в списке существующий дашборд и нажмите Создать.
    • Нажмите Добавить в новый дашборд, введите имя нового дашборда и нажмите Создать. Будет создан новый дашборд, на который автоматически добавится слой с данными.

Лимиты

  • Наборы для загрузки данных по API учитываются в общем лимите пользовательских данных. Чтобы посмотреть текущую статистику, нажмите значок Профиль в левом нижнем углу, перейдите в раздел Профиль и посмотрите значение в поле Пользовательские данные.
  • Максимальное общее количество объектов в наборе данных — 100 000. Чтобы увеличить этот лимит, обратитесь в поддержку.
  • Максимальное количество загружаемых объектов в одной операции — 100.
  • Максимальный размер тела запроса в PUT-запросах — 1 Мб.

Что дальше?