openapi: 3.2.0 info: title: Microsoft Azure Azure Maps Data Service Map Data API version: '1.0' description: APIs for uploading map data to Azure Maps. security: - AADToken: - https://atlas.microsoft.com/.default - SharedKey: [] - SasToken: [] tags: - name: Map Data paths: /mapData/upload: post: x-publish: true summary: Microsoft Azure The Upload Request Allows The Caller To Upload Data Content To… description: '**Applies to:** S1 pricing tier. The Data Upload 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. > [!NOTE] > > **Azure Maps Data service retirement** > > The Azure Maps Data service (both v1 and v2) is now deprecated and will be retired on 9/16/24. To avoid service disruptions, all calls to the Data service will need to be updated to use the Azure Maps Data Registry service by 9/16/24. For more information, see How to create data registry. ## Submit Upload Request To upload your content you will use a `POST` request. The request body will contain the data to upload. 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 using a center point and a radius. The sample below is in `GeoJSON`: ```json { "type": "FeatureCollection", "features": [{ "type": "Feature", "geometry": { "type": "Point", "coordinates": [-122.126986, 47.639754] }, "properties": { "geometryId": "001", "radius": 500 } }] } ``` The Data Upload API performs a long-running operation. ## Data Upload Limits Please, be aware that currently every Azure Maps account has a data storage limit. Once the 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.' operationId: microsoftAzureDataUploadpreview x-ms-long-running-operation: true x-ms-long-running-operation-options: final-state-via: location x-ms-examples: Upload GeoJSON data containing geometries that represent a collection of geofences: $ref: ./examples/Upload.json parameters: - $ref: '#/components/parameters/ClientId' - $ref: '#/components/parameters/SubscriptionKey' - $ref: '#/components/parameters/ApiVersion' - $ref: '#/components/parameters/UploadDataFormat' responses: '200': description: Data upload failed. The uploaded content did not satisfy all the validation checks. The response body contains all the errors that were encountered. content: application/json: schema: $ref: '#/components/schemas/ODataErrorResponse' '201': $ref: '#/components/responses/201Async' '202': $ref: '#/components/responses/202Async' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' tags: - Map Data requestBody: content: application/json: schema: type: object description: The content to upload. required: true /mapData/{udid}: put: x-publish: true summary: Microsoft Azure The Update Request Allows The Caller To Update Data Content… description: '**Applies to:** S1 pricing tier. The Data Update API allows the caller to update a previously uploaded data content. You can use this API in a scenario like adding or removing geofences to or from an existing collection of geofences. Geofences are uploaded using the Data Upload API, for use in the Azure Maps Geofencing Service. Please note that the Update API will *replace* and *override* the existing data content. > [!NOTE] > > **Azure Maps Data service retirement** > > The Azure Maps Data service (both v1 and v2) is now deprecated and will be retired on 9/16/24. To avoid service disruptions, all calls to the Data service will need to be updated to use the Azure Maps Data Registry service by 9/16/24. For more information, see How to create data registry. ## Submit Update Request To update your content you will use a `PUT` request. 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 be update. For example, to update a collection of geofences that were previously uploaded using the Upload API, place the new geofence content in the request body. 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 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. It''s represented as a circle geometry using a center point and a radius. The sample below is in `GeoJSON`: ```json { "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. The above request will update it to 500m. The Data Update API performs a long-running operation. ## Data Update Limits Please, be aware that currently every Azure Maps account has a data storage limit. Once the 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.' operationId: microsoftAzureDataUpdatepreview x-ms-long-running-operation: true x-ms-long-running-operation-options: final-state-via: location x-ms-examples: Update previously uploaded GeoJSON data containing geometries that represent a collection of geofences: $ref: ./examples/Update.json parameters: - $ref: '#/components/parameters/ClientId' - $ref: '#/components/parameters/SubscriptionKey' - $ref: '#/components/parameters/ApiVersion' - $ref: '#/components/parameters/Udid' responses: '200': description: Data update failed. The uploaded content did not satisfy all the validation checks. The response body contains all the errors that were encountered. content: application/json: schema: $ref: '#/components/schemas/ODataErrorResponse' '201': $ref: '#/components/responses/201Async' '202': $ref: '#/components/responses/202Async' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' tags: - Map Data requestBody: content: application/json: schema: type: object description: The new content that will update/replace the previously uploaded content. required: true get: x-publish: true summary: Microsoft Azure The Download Request Allows The Caller To Download Data… description: '**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. > [!NOTE] > > **Azure Maps Data service retirement** > > The Azure Maps Data service (both v1 and v2) is now deprecated and will be retired on 9/16/24. To avoid service disruptions, all calls to the Data service will need to be updated to use the Azure Maps Data Registry service by 9/16/24. For more information, see How to create data registry. ### 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: ```json { "type": "FeatureCollection", "features": [{ "type": "Feature", "geometry": { "type": "Point", "coordinates": [-122.126986, 47.639754] }, "properties": { "geometryId": "001", "radius": 500 } }] } ```' operationId: microsoftAzureDataDownloadpreview x-ms-examples: Download previously uploaded GeoJSON data containing geometries that represent a collection of geofences: $ref: ./examples/Download.json parameters: - $ref: '#/components/parameters/ClientId' - $ref: '#/components/parameters/SubscriptionKey' - $ref: '#/components/parameters/ApiVersion' - $ref: '#/components/parameters/Udid' responses: '200': description: Data download request completed successfully. The response body will contain the content for the passed in `udid`. headers: Content-Type: description: The content-type for the Download API response. schema: type: string content: application/json: schema: $ref: '#/components/schemas/MapDataDownloadResponse' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' tags: - Map Data delete: x-publish: true summary: Microsoft Azure The Delete Request Allows The Caller To Delete Data Previously… description: '**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. > [!NOTE] > > **Azure Maps Data service retirement** > > The Azure Maps Data service (both v1 and v2) is now deprecated and will be retired on 9/16/24. To avoid service disruptions, all calls to the Data service will need to be updated to use the Azure Maps Data Registry service by 9/16/24. For more information, see How to create data registry. ### 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.' operationId: microsoftAzureDataDeletepreview x-ms-examples: Delete previously uploaded GeoJSON data containing geometries that represent a collection of geofences: $ref: ./examples/Delete.json parameters: - $ref: '#/components/parameters/ClientId' - $ref: '#/components/parameters/SubscriptionKey' - $ref: '#/components/parameters/ApiVersion' - $ref: '#/components/parameters/Udid' responses: '204': description: Data delete request completed successfully. The content for `udid` was deleted on the server. content: application/json: schema: $ref: '#/components/schemas/MapDataDeleteResponse' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' tags: - Map Data /mapData: get: x-publish: true summary: Microsoft Azure The List Request Allows The Caller To Fetch A List Of All… description: '**Applies to:** S1 pricing tier. This API allows the caller to fetch a list of all content uploaded previously using the Data Upload API. > [!NOTE] > > **Azure Maps Data service retirement** > > The Azure Maps Data service (both v1 and v2) is now deprecated and will be retired on 9/16/24. To avoid service disruptions, all calls to the Data service will need to be updated to use the Azure Maps Data Registry service by 9/16/24. For more information, see How to create data registry. ### 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: ```json { "mapDataList": [ { "udid": "9a1288fa-1858-4a3b-b68d-13a8j5af7d7c", "location": "https://atlas.microsoft.com/mapData/9a1288fa-1858-4a3b-b68d-13a8j5af7d7c?api-version=1.0", "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", "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", "sizeInBytes": 1650, "uploadStatus": "Pending" }] } ```' operationId: microsoftAzureDataListpreview x-ms-examples: List all the previously uploaded data: $ref: ./examples/List.json parameters: - $ref: '#/components/parameters/ClientId' - $ref: '#/components/parameters/SubscriptionKey' - $ref: '#/components/parameters/ApiVersion' responses: '200': description: List data request completed successfully. The response body contains a list of all the previously uploaded data. headers: Content-Type: description: The content-type for the Download API response. schema: type: string content: application/json: schema: $ref: '#/components/schemas/MapDataListResponse' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '500': $ref: '#/components/responses/500' tags: - Map Data components: schemas: ODataError: type: object description: This object is returned when an error occurs in the Azure Maps API. properties: code: type: string readOnly: true description: The ODataError code. message: type: string readOnly: true description: If available, a human-readable description of the error. details: type: array items: $ref: '#/components/schemas/ODataError' target: type: string readOnly: true description: If available, the target causing the error. MapDataListResponse: description: The response model for the Data List API. Returns a list of all the previously uploaded data. type: object properties: mapDataList: description: A list of all the previously uploaded data. type: array readOnly: true items: $ref: '#/components/schemas/MapDataDetailInfo' ODataErrorResponse: type: object description: This response object is returned when an error occurs in the Azure Maps API. properties: error: $ref: '#/components/schemas/ODataError' MapDataDeleteResponse: description: The response model for the Data Delete API. The response body will be empty signifying there's no content available for the `udid` anymore. type: object MapDataDetailInfo: description: Detail information for the data. type: object properties: udid: description: The unique data id for the data. type: string readOnly: true location: description: The location of the data. Execute a HTTP `GET` on this location to download the data. type: string readOnly: true sizeInBytes: description: The size of the content in bytes. type: integer format: int64 readOnly: true uploadStatus: description: The current upload status of the content. type: string readOnly: true MapDataDownloadResponse: description: The response model for the Data Download API. The response body will contain the content for the passed in `udid`. type: object LongRunningOperationResult: description: The response model for a Long-Running Operations API. type: object properties: operationId: description: The Id for this long-running operation. type: string status: description: The status state of the request. type: string enum: - NotStarted - Running - Failed - Succeeded x-ms-enum: name: type modelAsString: true values: - value: NotStarted description: The request has not started processing yet. - value: Running description: The request has started processing. - value: Failed description: The request has one or more failures. - value: Succeeded description: The request has successfully completed. readOnly: true created: description: The created timestamp. type: string readOnly: true resourceLocation: description: The location URI for details about the created resource. This is only provided when the request was successfully completed. type: string readOnly: true error: $ref: '#/components/schemas/ODataError' warning: $ref: '#/components/schemas/ODataError' responses: 202Async: description: '**Supported only for async request.** Request Accepted: The request has been accepted for processing. Please use the URL in the Location Header to retry or access the results.' headers: Location: description: New URL to check for the results of the long-running operation. schema: type: string '400': description: 'Bad request: one or more parameters were incorrectly specified or are mutually exclusive.' content: application/json: schema: $ref: '#/components/schemas/ODataErrorResponse' '403': description: Permission, capacity, or authentication issues. content: application/json: schema: $ref: '#/components/schemas/ODataErrorResponse' '401': description: Access denied due to invalid subscription key or invalid Microsoft Entra ID bearer token. Make sure to provide a valid key for an active Azure subscription and Maps resource. Otherwise, verify the [WWW-Authenticate](https://tools.ietf.org/html/rfc6750#section-3.1) header for error code and description of the provided Microsoft Entra ID bearer token. headers: WWW-Authenticate: description: Bearer realm="https://atlas.microsoft.com/", error="invalid_token", error_description="The access token expired" schema: type: string content: application/json: schema: $ref: '#/components/schemas/ODataErrorResponse' '404': description: 'Not Found: the requested resource could not be found, but it may be available again in the future.' content: application/json: schema: $ref: '#/components/schemas/ODataErrorResponse' 201Async: description: The resource has been created successfully. headers: Location: description: A URI where details on the newly created resource can be found. schema: type: string content: application/json: schema: $ref: '#/components/schemas/LongRunningOperationResult' '500': description: An error occurred while processing the request. Please try again later. content: application/json: schema: $ref: '#/components/schemas/ODataErrorResponse' parameters: Udid: name: udid description: The unique data id for the content. The `udid` must have been obtained from a successful [Data Upload API](/rest/api/maps/data/upload?view=rest-maps-1.0) call. in: path required: true x-ms-parameter-location: method schema: type: string ApiVersion: name: api-version description: Version number of Azure Maps API. Current version is 1.0 in: query required: true x-ms-parameter-location: client schema: type: string default: '1.0' SubscriptionKey: name: subscription-key description: One of the Azure Maps keys provided from an Azure Map Account. Please refer to this [article](/azure/azure-maps/how-to-manage-authentication) for details on how to manage authentication. in: query required: false x-ms-parameter-location: client schema: type: string UploadDataFormat: name: dataFormat description: Data format of the content being uploaded. in: query required: true x-ms-enum: name: UploadDataFormat modelAsString: true values: - value: geojson description: '[GeoJSON](https://tools.ietf.org/html/rfc7946) is a JSON based geospatial data interchange format.' - value: zip description: Compressed data format. x-ms-parameter-location: method schema: type: string enum: - geojson - zip ClientId: name: x-ms-client-id description: Specifies which account is intended for usage in conjunction with the Microsoft Entra ID security model. It represents a unique ID for the Azure Maps account and can be retrieved from the Azure Maps management plane Account API. To use Microsoft Entra ID security in Azure Maps see the following [articles](https://aka.ms/amauthdetails) for guidance. in: header required: false x-ms-parameter-location: client schema: type: string securitySchemes: AADToken: type: oauth2 flows: implicit: scopes: https://atlas.microsoft.com/.default: https://atlas.microsoft.com/.default authorizationUrl: https://login.microsoftonline.com/common/oauth2/authorize description: "These are the [Microsoft Entra OAuth 2.0](/azure/active-directory/develop/v1-overview) Flows. When paired with [Azure role-based access](/azure/role-based-access-control/overview) control it can be used to control access to Azure Maps REST APIs. Azure role-based access controls are used to designate access to one or more Azure Maps resource account or sub-resources. Any user, group, or service principal can be granted access via a built-in role or a custom role composed of one or more permissions to Azure Maps REST APIs.\n\nTo implement scenarios, we recommend viewing [authentication concepts](https://aka.ms/amauth). In summary, this security definition provides a solution for modeling application(s) via objects capable of access control on specific APIs and scopes.\n\n#### Notes\n* This security definition **requires** the use of the `x-ms-client-id` header to indicate which Azure Maps resource the application is requesting access to. This can be acquired from the [Maps management API](https://aka.ms/amauthdetails).\n* \nThe `Authorization URL` is specific to the Azure public cloud instance. Sovereign clouds have unique Authorization URLs and Microsoft Entra ID configurations. \n* \nThe Azure role-based access control is configured from the [Azure management plane](https://aka.ms/amrbac) via Azure portal, PowerShell, CLI, Azure SDKs, or REST APIs.\n* \nUsage of the [Azure Maps Web SDK](https://aka.ms/amaadmc) allows for configuration based setup of an application for multiple use cases.\n* For more information on Microsoft identity platform, see [Microsoft identity platform overview](/entra/identity-platform/v2-overview)." SharedKey: type: apiKey description: "This is a shared key that is provisioned when you [Create an Azure Maps account](/azure/azure-maps/quick-demo-map-app#create-an-azure-maps-account) in the Azure portal or using PowerShell, CLI, Azure SDKs, or REST API.\n\n With this key, any application can access all REST API. In other words, this key can be used as a master key in the account that they are issued in.\n\n For publicly exposed applications, our recommendation is to use the [confidential client applications](/azure/azure-maps/authentication-best-practices#confidential-client-applications) approach to access Azure Maps REST APIs so your key can be securely stored." name: subscription-key in: query SasToken: type: apiKey description: "This is a shared access signature token is created from the List SAS operation on the [Azure Maps resource](https://aka.ms/amauth) through the Azure management plane via Azure portal, PowerShell, CLI, Azure SDKs, or REST APIs.\n\n With this token, any application is authorized to access with Azure role-based access controls and fine-grain control to the expiration, rate, and region(s) of use for the particular token. In other words, the SAS Token can be used to allow applications to control access in a more secured way than the shared key.\n\n For publicly exposed applications, our recommendation is to configure a specific list of allowed origins on the [Map account resource](https://aka.ms/amauth) to limit rendering abuse and regularly renew the SAS Token." name: SAS Token in: header x-ms-parameterized-host: hostTemplate: '{geography}.atlas.microsoft.com' parameters: - $ref: '#/components/parameters/GeographicResourceLocation'