Data

Operations

Delete Preview

Data Delete API

Applies to: S1 pricing tier.

This API allows the caller to delete a previously uploaded data content.

You can use this API in a scenario like removing geofences previously uploaded using the Data Upload API for use in our Azure Maps Geofencing Service. You can also use this API to delete old/unused uploaded content and create space for new content.

Submit Delete Request

To delete your content you will issue a DELETE request where the path will contain the udid of the data to delete.

For example, to delete a collection of geofences previously uploaded using the Upload API, set the udid parameter in the path to the udid of the data received previously in the upload API response.

Delete Data Response

The Data Delete API returns a HTTP 204 No Content response with an empty body, if the data resource was deleted successfully.

A HTTP 400 Bad Request error response will be returned if the data resource with the passed-in udid is not found.

Download Preview

Data Download API

Applies to: S1 pricing tier.

This API allows the caller to download a previously uploaded data content.

You can use this API in a scenario like downloading an existing collection of geofences uploaded previously using the Data Upload API for use in our Azure Maps Geofencing Service.

Submit Download Request

To download your content you will use a GET request where the path will contain the udid of the data to download. Optionally, you can also pass in an Accept header to specify a preference for the Content-Type of the data response.
For example, to download a collection of geofences previously uploaded using the Upload API, set the udid parameter in the path to the udid of the data received previously in the upload API response and set the Accept header to either one of the following media types:

  • application/json
  • application/vnd.geo+json
  • application/octet-stream

Download Data Response

The Download API will return a HTTP 200 OK response if the data resource with the passed-in udid is found, where the response body will contain the content of the data resource.
A HTTP 400 Bad Request error response will be returned if the data resource with the passed-in udid is not found.

Here's a sample response body for a simple geofence represented in GeoJSON uploaded previously using the Upload API:

{
    "type": "FeatureCollection",
    "features": [{
        "type": "Feature",
        "geometry": {
            "type": "Point",
            "coordinates": [-122.126986, 47.639754]
        },
        "properties": {
            "geometryId": "001",
            "radius": 500
        }
    }]
}
List Preview

Data List API

Applies to: S1 pricing tier.

This API allows the caller to fetch a list of all content uploaded previously using the Data Upload API.

Submit List Request

To list all your map data content you will issue a GET request with no additional parameters.

List Data Response

The Data List API returns the complete list of all data in json format. The response contains the following details for each data resource:

udid - The unique data id for the data resource.

location - The location of the data resource. Execute a HTTP GET on this location to download the data.

Here's a sample response returning the udid and location of 3 data resources:


{
    "mapDataList": 
    [
        {
            "udid": "9a1288fa-1858-4a3b-b68d-13a8j5af7d7c",
            "location": "https://atlas.microsoft.com/mapData/9a1288fa-1858-4a3b-b68d-13a8j5af7d7c?api-version=1.0&subscription-key={subscription-key}",
            "sizeInBytes": 29920,
            "uploadStatus": "Completed"
        },
        {
            "udid": "8b1288fa-1958-4a2b-b68e-13a7i5af7d7c",
            "location": "https://atlas.microsoft.com/mapData/8b1288fa-1958-4a2b-b68e-13a7i5af7d7c?api-version=1.0&subscription-key={subscription-key}",
            "sizeInBytes": 1339,
            "uploadStatus": "Completed"
        },
        {
            "udid": "7c1288fa-2058-4a1b-b68f-13a6h5af7d7c",
            "location": "https://atlas.microsoft.com/mapData/7c1288fa-2058-4a1b-b68f-13a6h5af7d7c?api-version=1.0&subscription-key={subscription-key}",
            "sizeInBytes": 1650,
            "uploadStatus": "Pending"
        }]
}

Update Preview

Data Update API

Applies to: S1 pricing tier.

This API allows the caller to update a previously uploaded data content.

You can use this API in a scenario like adding/removing geofences to/from an existing collection of geofences uploaded previously using the Data Upload API for use in our Azure Maps Geofencing Service.
Please note that the Update API will replace/override the existing data content.

Submit Update Request

To update your content you will use a PUT request where the request body will contain the new data that will replace the existing data, the Content-Type header will be set to the content type of the data and the path will contain the udid of the data to update.

For example, to update a collection of geofences previously uploaded using the Upload API, set the request body to the new geofence content, set the udid parameter in the path to the udid of the data received previously in the upload API response and set the Content-Type header to either one of the following media types:

  • application/json
  • application/vnd.geo+json
  • application/octet-stream

Here's a sample request body for updating a simple Geofence represented as a circle geometry in GeoJSON using a center point and a radius:


{
    "type": "FeatureCollection",
    "features": [{
        "type": "Feature",
        "geometry": {
            "type": "Point",
            "coordinates": [-122.126986, 47.639754]
        },
        "properties": {
            "geometryId": "001",
            "radius": 500
        }
    }]
}


The previously uploaded geofence had a radius of 100m. This request will update it to 500m.
The Data Update API is a long-running request with the following sequence of operations:

Send the update request

  1. Client sends a Data Update PUT request to Azure Maps

  2. The server will respond with one of the following:

    HTTP 202 Accepted - Update request has been accepted.

    HTTP Error - There was an error processing your Update request. This could either be a 400 Bad Request or any other Error status code.

  3. If the Update request was accepted successfully, the Location header in the response contains the status URI to check the current status of the long-running update request. This status URI looks like the following:

https://atlas.microsoft.com/mapData/{udid}/status?api-version=1.0&subscription-key={subscription-key}    

Update request "Accepted" but "In Progress"

  1. Client issues a GET request on the status URI obtained above to check the current status of the update request.

  2. At this point, if the update request is still being processed by Azure Maps, the client receives a HTTP 202 Accepted response. The Location header in the response contains the status URI to check the current status of the long-running update request. The response body contains a more detailed status for the request which looks like:

{
    "status" : "In Progress"         
}

Update request "Completed" successfully

  1. Client issues another GET request on the status URI to check the current update status.

  2. At this point, if the update request processing has completed successfully, the client receives a HTTP 201 Created response.

  3. The update request was successful and the data has been created. The Location header in the response contains the URI to access/download the content in the future. The response body contains a unique data id (udid) for the data and looks like:

{
    "udid" : "d7e5efc8-2239-4387-a286-5bb51aa804e3"         
}

Update request "Failed"

  1. Client issues another GET request on the status URI to check the current update status.

  2. At this point, if the update request processing has failed, the client receives a HTTP 204 No Content response.

  3. The request has failed and the data has not been created. The response body will contain a list of errors encountered while processing the update request:

{
    "error": 
    {
      "code": "204 No Content",
      "message": "Update data request failed. We encountered the following problems with your data: Data is not a valid GeoJSON"
    }         
}

Data Update Limits

Please, be aware that currently every Azure Maps account gets a free storage limit of 50 MB. This means that you can either upload 1 document of size 50 MB or 5 documents, each of size 10 MB or 100 documents, each of size 500 KB and so on. Once the free storage limit is reached, all the new Update API calls will return a 409 Conflict http error response. You can always use the Data Delete API to delete old/unused content and create space for new uploads/updates.


Upload Preview

Data Upload API

Applies to: S1 pricing tier.

This API allows the caller to upload data content to the Azure Maps service.

You can use this API in a scenario like uploading a collection of Geofences in GeoJSON format for use in our Azure Maps Geofencing Service.

Submit Upload Request

To upload your content you will use a POST request where the request body will contain the data to upload, the dataFormat query parameter will contain the format for the data, the dataSharingLevel query parameter can contain the sharing level for the data and the Content-Type header will be set to the content type of the data.

For example, to upload a collection of geofences in GeoJSON format, set the request body to the geofence content, set the dataFormat query parameter to geojson and set the Content-Type header to either one of the following media types:

  • application/json
  • application/vnd.geo+json
  • application/octet-stream

Here's a sample request body for uploading a simple Geofence represented as a circle geometry in GeoJSON using a center point and a radius:


{
    "type": "FeatureCollection",
    "features": [{
        "type": "Feature",
        "geometry": {
            "type": "Point",
            "coordinates": [-122.126986, 47.639754]
        },
        "properties": {
            "geometryId": "001",
            "radius": 500
        }
    }]
}


The Data Upload API is a long-running request with the following sequence of operations:

Send the upload request

  1. Client sends a Data Upload POST request to Azure Maps

  2. The server will respond with one of the following:

    HTTP 202 Accepted - Upload request has been accepted.

    HTTP Error - There was an error processing your Upload request. This could either be a 400 Bad Request or any other Error status code.

  3. If the Upload request was accepted successfully, the Location header in the response contains the status URI to check the current status of the long-running upload request. This status URI looks like the following:

https://atlas.microsoft.com/mapData/{udid}/status?api-version=1.0&subscription-key={subscription-key}    

Upload request "Accepted" but "In Progress"

  1. Client issues a GET request on the status URI obtained above to check the current status of the upload request.

  2. At this point, if the upload request is still being processed by Azure Maps, the client receives a HTTP 202 Accepted response. The Location header in the response contains the status URI to check the current status of the long-running upload request. The response body contains a more detailed status for the request which looks like:

{
    "status" : "In Progress"         
}

Upload request "Completed" successfully

  1. Client issues another GET request on the status URI to check the current upload status.

  2. At this point, if the upload request processing has completed successfully, the client receives a HTTP 201 Created response.

  3. The upload request was successful and the data has been created. The Location header in the response contains the URI to access/download the content in the future. The response body contains a unique data id (udid) for the data and looks like:

{
    "udid" : "d7e5efc8-2239-4387-a286-5bb51aa804e3"         
}

Upload request "Failed"

  1. Client issues another GET request on the status URI to check the current upload status.

  2. At this point, if the upload request processing has failed, the client receives a HTTP 204 No Content response.

  3. The request has failed and the data has not been created. The response body will contain a list of errors encountered while processing the upload request:

{
    "error": 
    {
      "code": "204 No Content",
      "message": "Upload data request failed. We encountered the following problems with your data: Map data is not a valid GeoJSON"
    }         
}

Data Upload Limits

Please, be aware that currently every Azure Maps account gets a free storage limit of 50 MB. This means that you can either upload 1 document of size 50 MB or 5 documents, each of size 10 MB or 100 documents, each of size 500 KB and so on. Once the free storage limit is reached, all the new upload API calls will return a 409 Conflict http error response. You can always use the Data Delete API to delete old/unused content and create space for new uploads.