Microsoft Azure Map Data API

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:
    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'
    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
    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
    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.
    ODataErrorResponse:
      type: object
      description: This response object is returned when an error occurs in the Azure Maps API.
      properties:
        error:
          $ref: '#/components/schemas/ODataError'
    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'
    MapDataDownloadResponse:
      description: The response model for the Data Download API. The response body will contain the content for the passed in `udid`.
      type: object
  parameters:
    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
    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
    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
    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'
  responses:
    '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'
    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'
    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'
    '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'
  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'