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.
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
- Open the Urbi Pro interface in a browser and open Developer Tools (press F12).
- In the Pro interface, click icon to open the profile tab.
- In the Develop Tools panel, click a new
user?include_permissions=true
row that appears in the Networks tab. - 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 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.
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 Urbi 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 Urbi Pro interface.
- Dataset ID (
-
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 } } ] }
-
-
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.
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 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.
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 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.
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 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.
-
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
- Open the Urbi Pro interface.
- Go to the Data tab.
- On the required dataset card, click icon and select Delete.
- To confirm deleting, click Delete.
What's next?
- Quick start.
- API Reference.
- Get to know how to work with Data visualization.
- Get to know more about Layers, Dashboards, and Widgets.
- Get to know prepared Analytics presets.