Microsoft Azure mapData API

openapi: 3.2.0
info:
  version: 2020-08-01-preview
  title: Microsoft Azure AccessControlClient AccessConnector Map Data API
tags:
- name: mapData
paths:
  /mapData/upload:
    post:
      x-publish: true
      summary: Microsoft Azure The Upload Request Allows The Caller To Upload Data Content To Their Azure Maps Account
      description: '**Applies to:** S1 pricing tier.<br><br>The Data Upload API allows the caller to upload data content to the Azure Maps service.<br>You can use this API in a scenario like uploading a collection of Geofences in `GeoJSON` <br>format, for use in our [Azure Maps Geofencing Service](/rest/api/maps/spatial).<br><br>> [!NOTE]<br>><br>> **Azure Maps Data service retirement**<br>><br>> The Azure Maps Data service (both [v1](/rest/api/maps/data?view=rest-maps-1.0) and [v2](/rest/api/maps/data)) 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](/rest/api/maps/data-registry) service by 9/16/24. For more information, see [How to create data registry](/azure/azure-maps/how-to-create-data-registries).<br><br>## Submit Upload Request<br><br>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 <br>data.<br><br>For example, to upload a collection of geofences  in `GeoJSON` format, set the request body to the geofence <br>content. Set the `dataFormat` query parameter to _geojson_, and set the `Content-Type` header to either one <br>of the following media types:<br><br>- `application/json`<br>- `application/vnd.geo+json`<br>- `application/octet-stream`<br><br>Here''s a sample request body for uploading a simple Geofence represented as a circle geometry using a center <br>point and a radius. The sample below is in `GeoJSON`:<br><br>```json<br>{<br>    "type": "FeatureCollection",<br>    "features": [{<br>        "type": "Feature",<br>        "geometry": {<br>            "type": "Point",<br>            "coordinates": [-122.126986, 47.639754]<br>        },<br>        "properties": {<br>            "geometryId": "001",<br>            "radius": 500<br>        }<br>    }]<br>}<br>```<br><br>The Data Upload API performs a <br>long-running operation.<br><br>## Data Upload Limits<br><br>Please, be aware that currently every Azure Maps account has a [data storage limit](/azure/azure-resource-manager/management/azure-subscription-service-limits#azure-maps-limits). <br>Once the storage limit is reached, all the new upload API calls will return a `409 Conflict` http error response. <br>You can always use the [Data Delete API](/rest/api/maps/data/delete?view=rest-maps-1.0) to <br>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:
      - mapData
      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 Previously Uploaded Using [data Upload] Rest Api Maps Data Upload Preview?view Rest Maps 1 0
      description: '**Applies to:** S1 pricing tier.<br><br>The Data Update API allows the caller to update a previously uploaded data content.<br><br>You can use this API in a scenario like adding or removing geofences to or from an existing collection of geofences. <br>Geofences are uploaded using the [Data Upload API](/rest/api/maps/data/upload?view=rest-maps-1.0), for <br>use in the [Azure Maps Geofencing Service](/rest/api/maps/spatial).<br><br>Please note that the Update API will *replace* and *override* the existing data content.<br><br>> [!NOTE]<br>><br>> **Azure Maps Data service retirement**<br>><br>> The Azure Maps Data service (both [v1](/rest/api/maps/data?view=rest-maps-1.0) and [v2](/rest/api/maps/data)) 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](/rest/api/maps/data-registry) service by 9/16/24. For more information, see [How to create data registry](/azure/azure-maps/how-to-create-data-registries).<br><br>## Submit Update Request<br><br>To update your content you will use a `PUT` request. The request body will contain the new data that will replace <br>the existing data. The `Content-Type` header will be set to the content type of the data, and the path will contain <br>the `udid` of the data to be update.<br><br>For example, to update a collection of geofences that were previously uploaded using the Upload API, place the new <br>geofence content in the request body. Set the `udid` parameter in the path to the `udid` of the data received <br>previously in the upload API response. And set the `Content-Type` header to one of the following media types:<br><br>- `application/json`<br>- `application/vnd.geo+json`<br>- `application/octet-stream`<br><br>Here''s a sample request body for updating a simple Geofence. It''s represented as a circle geometry using a center <br>point and a radius. The sample below is in `GeoJSON`:<br><br>```json<br>{<br>    "type": "FeatureCollection",<br>    "features": [{<br>        "type": "Feature",<br>        "geometry": {<br>            "type": "Point",<br>            "coordinates": [-122.126986, 47.639754]<br>        },<br>        "properties": {<br>            "geometryId": "001",<br>            "radius": 500<br>        }<br>    }]<br>}<br>```<br><br>The previously uploaded geofence had a radius of 100m. The above request will update it to 500m.<br><br>The Data Update API performs a <br>long-running operation.<br><br>## Data Update Limits<br><br>Please, be aware that currently every Azure Maps account has a [data storage limit](/azure/azure-resource-manager/management/azure-subscription-service-limits#azure-maps-limits). <br>Once the storage limit is reached, all the new upload API calls will return a `409 Conflict` http error response. <br>You can always use the [Data Delete API](/rest/api/maps/data/delete?view=rest-maps-1.0) to <br>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:
      - mapData
      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 Previously Uploaded Using [data Upload] Rest Api Maps Data Upload Preview?view Rest Maps 1 0
      description: '**Applies to:** S1 pricing tier.<br><br><br>This API allows the caller to download a previously uploaded data content.<br>You can use this API in a scenario like downloading an existing collection of geofences uploaded previously using the [Data Upload API](/rest/api/maps/data/upload?view=rest-maps-1.0) for use in our [Azure Maps Geofencing Service](/rest/api/maps/spatial).<br><br>> [!NOTE]<br>><br>> **Azure Maps Data service retirement**<br>><br>> The Azure Maps Data service (both [v1](/rest/api/maps/data?view=rest-maps-1.0) and [v2](/rest/api/maps/data)) 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](/rest/api/maps/data-registry) service by 9/16/24. For more information, see [How to create data registry](/azure/azure-maps/how-to-create-data-registries).<br><br><br>### Submit Download Request<br><br>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. <br>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: <br>    <br>  - `application/json`<br>  - `application/vnd.geo+json`<br>  - `application/octet-stream`<br><br><br>### Download Data Response<br><br>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.<br>A HTTP `400 Bad Request` error response will be returned if the data resource with the passed-in `udid` is not found.<br><br>Here''s a sample response body for a simple geofence represented in `GeoJSON` uploaded previously using the Upload API:<br><br><br>```json<br>{<br>    "type": "FeatureCollection",<br>    "features": [{<br>        "type": "Feature",<br>        "geometry": {<br>            "type": "Point",<br>            "coordinates": [-122.126986, 47.639754]<br>        },<br>        "properties": {<br>            "geometryId": "001",<br>            "radius": 500<br>        }<br>    }]<br>}<br>```'
      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:
      - mapData
    delete:
      x-publish: true
      summary: Microsoft Azure The Delete Request Allows The Caller To Delete Data Previously Uploaded Using [data Upload] Rest Api Maps Data Upload Preview?view Rest Maps 1 0
      description: '**Applies to:** S1 pricing tier.<br><br><br>This API allows the caller to delete a previously uploaded data content.    <br>You can use this API in a scenario like removing geofences previously uploaded using the [Data Upload API](/rest/api/maps/data/upload?view=rest-maps-1.0) for use in our [Azure Maps Geofencing Service](/rest/api/maps/spatial). You can also use this API to delete old/unused uploaded content and create space for new content.<br><br>> [!NOTE]<br>><br>> **Azure Maps Data service retirement**<br>><br>> The Azure Maps Data service (both [v1](/rest/api/maps/data?view=rest-maps-1.0) and [v2](/rest/api/maps/data)) 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](/rest/api/maps/data-registry) service by 9/16/24. For more information, see [How to create data registry](/azure/azure-maps/how-to-create-data-registries).<br><br><br>### Submit Delete Request<br><br>To delete your content you will issue a `DELETE` request where the path will contain the `udid` of the data to delete.    <br>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. <br><br><br>### Delete Data Response<br><br>The Data Delete API returns a HTTP `204 No Content` response with an empty body, if the data resource was deleted successfully.    <br>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:
      - mapData
  /mapData:
    get:
      x-publish: true
      summary: Microsoft Azure The List Request Allows The Caller To Fetch A List Of All Content Previously Uploaded Using [data Upload] Rest Api Maps Data Upload?view Rest Maps 1 0
      description: '**Applies to:** S1 pricing tier.<br><br><br>This API allows the caller to fetch a list of all content uploaded previously using the [Data Upload API](/rest/api/maps/data/upload?view=rest-maps-1.0).<br><br>> [!NOTE]<br>><br>> **Azure Maps Data service retirement**<br>><br>> The Azure Maps Data service (both [v1](/rest/api/maps/data?view=rest-maps-1.0) and [v2](/rest/api/maps/data)) 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](/rest/api/maps/data-registry) service by 9/16/24. For more information, see [How to create data registry](/azure/azure-maps/how-to-create-data-registries).<br><br><br>### Submit List Request<br><br>To list all your map data content you will issue a `GET` request with no additional parameters.<br><br><br>### List Data Response<br><br>The Data List API returns the complete list of all data in `json` format. The response contains the following details for each data resource:<br><br>  > udid - The unique data id for the data resource.<br><br>  > location - The location of the data resource. Execute a HTTP `GET` on this location to download the data.<br><br><br>Here''s a sample response returning the `udid` and `location` of 3 data resources:  <br><br><br><br>```json<br>{<br>    "mapDataList": <br>    [<br>        {<br>            "udid": "9a1288fa-1858-4a3b-b68d-13a8j5af7d7c",<br>            "location": "https://atlas.microsoft.com/mapData/9a1288fa-1858-4a3b-b68d-13a8j5af7d7c?api-version=1.0",<br>            "sizeInBytes": 29920,<br>            "uploadStatus": "Completed"<br>        },<br>        {<br>            "udid": "8b1288fa-1958-4a2b-b68e-13a7i5af7d7c",<br>            "location": "https://atlas.microsoft.com/mapData/8b1288fa-1958-4a2b-b68e-13a7i5af7d7c?api-version=1.0",<br>            "sizeInBytes": 1339,<br>            "uploadStatus": "Completed"<br>        },<br>        {<br>            "udid": "7c1288fa-2058-4a1b-b68f-13a6h5af7d7c",<br>            "location": "https://atlas.microsoft.com/mapData/7c1288fa-2058-4a1b-b68f-13a6h5af7d7c?api-version=1.0",<br>            "sizeInBytes": 1650,<br>            "uploadStatus": "Pending"<br>        }]<br>}<br>```<br><br>'
      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:
      - mapData
components:
  schemas:
    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'
    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'
    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
    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.
  parameters:
    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
    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
    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:
    '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'
    '400':
      description: 'Bad request: one or more parameters were incorrectly specified or are mutually exclusive.'
      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'
    '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'
    '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
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - $ref: '#/components/parameters/Endpoint'