Pushing data via API | Urbi Pro | 2GIS Documentation
Urbi Pro

Uploading data using API

You can upload (push) data from external sources to Urbi Pro using API. This is the best method for working with volatile data.

Note

You can upload data via API only to a separate dataset that you create following the steps below. You cannot use API to upload data to system datasets.

  1. Create an empty dataset to store uploaded data:

    1. Send a POST request to /dynamic_asset:

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

      Use your Bearer token for authorization.

      How to get a Bearer token
      1. Open the Urbi Pro interface in a browser and open Developer Tools (press F12).
      2. In the Pro interface, click Profile icon to open the profile tab.
      3. In the Develop Tools panel, click a new user?include_permissions=true row that appears in the Networks tab.
      4. In the opened table, find the Authorization: row and copy symbols after Bearer. Use these symbols as your authorization token.

    2. In the request body, pass the JSON with the necessary parameters:

      • geometry_dimension: geometry type (point, line, polygon). Mandatory parameter.
      • name: dataset name. Mandatory parameter.
      • description: dataset description.
      • attribute_groups: list of data attributes. You can set not more than 100 attributes of each type.
      • filters: settings of data filters: UI control type, list of values, and others.

      For more information about parameters, see the API Reference

      Request body example
      {
          "geometry_dimension": "polygon",
          "name": "Cars on city map",
          "description": "Shows car positions on the map",
          "attribute_groups": [
              {
                  "name": "Main features",
                  "attributes": [
                      {
                          "id": "Model",
                          "type": "string",
                          "caption": "Model"
                      },
                      {
                          "id": "Year",
                          "type": "number",
                          "caption": "Release year"
                      }
                  ]
              }
          ],
          "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
              }
          ]
      }
      

    If the request is handled successfully, a response with a dataset ID (asset_id parameter) and an access token (access_token parameter) is returned.

  2. Open the Urbi Pro interface and refresh the page. The created dataset appears in the uploaded data section.

    Note

    Creating a dataset might take a while. If the dataset does not appear in the interface immediately, try refreshing the page later.

    New dynamic dataset

    To see the configured filters, open the dataset and select a territory (as data is not uploaded yet, results are empty).

    Dynamic dataset filters

To push a portion of data to Urbi Pro:

  1. Send a PUT request to /dynamic_asset:

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

    You need the following data that you received when creating a dataset:

    • Dataset ID (assetId). You can copy it from the Pro interface: open the created dataset and copy the value between ...assetId/ and ?m=... from the opened page address.
    • Access token for authorization. You can find it in your profile tab in the Urbi Pro interface.
  2. In the request body, pass data in the GeoJSON format:

    • type: GeoJSON object type.

    • features: object parameters:

      • type: GeoJSON object type.

      • geometry: object geometry in the JSON format.

      • id: object identifier.

      • properties: object properties according to the data attributes set during dataset creation.

        If names or values of the object properties differ from the ones set during dataset creation, all new values are displayed in the object card but are not considered in the filter settings. To update filters, send a request to change dataset metadata.

    For more information about parameters, see the API Reference.

    Request body example
    {
        "type": "FeatureCollection",
        "features": [
            {
                "id": "1",
                "type": "Feature",
                "geometry": {
                    "type": "Polygon",
                    "coordinates": [
                        [
                            [55.23113694972383, 25.13910052107302],
                            [55.23113694972383, 25.102428900376935],
                            [55.300267281803826, 25.102428900376935],
                            [55.300267281803826, 25.13910052107302],
                            [55.23113694972383, 25.13910052107302]
                        ]
                    ]
                },
                "properties": {
                    "Model": "Citroen C3",
                    "Year": 2002
                }
            }
        ]
    }
    
  3. Open the Urbi Pro interface, refresh the page, and select the required dataset. Uploaded data is displayed on the map.

    Note

    Uploading data usually takes around one minute. If the data is not displayed immediately, try refreshing the page later.

Dynamic dataset with uploaded data
  • Datasets for uploading data using API are counted in the total limit of user data. You can find the current statistics in your profile tab in the Urbi Pro interface.
  • Maximum total number of objects in a dataset - 100.000. To extend this limit, contact support.
  • Maximum number of objects uploaded in one operation - 1000.
  • Maximum size of the request body in PUT requests - 1 Mb.

To send the requests below, you need the following data that you received when creating a dataset:

  • Dataset ID.

    You can copy it from the Urbi Pro interface: open the created dataset and copy the value between ...assetId/ and ?m=... from the opened page address.

  • Access token for authorization.

    You can find it in your profile tab in the Urbi Pro interface.

Send a GET request to /dynamic_asset and specify the ID of the created dataset (assetId parameter):

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

For more information about the response body, see the API Reference.

Important

If you add a new filter for an existing attribute, the filter only works for new data uploaded after the filer was added. Old data is not indexed. To index all data, you can add a new attribute together with a new filter.

  1. Send a PUT request to /dynamic_asset:

    https://pro-api.2gis.ru/dynamic_asset
    
  2. In the request body, pass a JSON with the dataset ID and name and other parameters that must be changed.

    For the full list of parameters, see the API Reference.

  1. Send a DELETE request to /dynamic_asset and specify the ID of the created dataset (assetId parameter):

    • To remove a part of objects:

      https://pro-api.2gis.ru/dynamic_asset/{assetId}/data
      
    • To remove all objects:

      https://pro-api.2gis.ru/dynamic_asset/{assetId}/data/all
      
  2. If you want to remove only a part of objects, pass a request body with a JSON with object IDs to delete.

For more information about parameters, see the API Reference.

  1. Open the Urbi Pro interface.
  2. Go to the Data tab.
  3. On the required dataset card, click Dataset menu icon and select Delete.
  4. To confirm deleting, click Delete.