Uploading data using API

You can upload (push) data from external sources to 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.

Getting started

Create an empty dataset to store uploaded data:

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 Pro interface in a browser and open Developer Tools (press F12).
2. In the Pro interface, click 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.

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.

Open the 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.

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

Uploading data

To push a portion of data to Pro:

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 Pro interface.

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 will be displayed in the object card but will not be 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
            }
        }
    ]
}

Open the 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.

Limits

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

Operations with uploaded data

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 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 Pro interface.

Getting dataset parameters

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.

Changing dataset parameters

Important

If you add a new filter for an existing attribute, the filter will only work 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.

Send a PUT request to /dynamic_asset:
```
https://pro-api.2gis.ru/dynamic_asset
```
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.

Deleting objects from dataset

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

Deleting a dataset

Hover the cursor over the uploaded data card.
Click icon and select Delete.
Confirm the deletion by clicking Delete.

What's next?

API Reference.
Get to know how to work with Layers.
Get to know more about data Visualization.
Get to know Analytics presets.