Microsoft Azure Maps Feedback Service

swagger: '2.0'
info:
  title: Microsoft Azure Azure Maps Feedback Service
  version: '1.0'
host: atlas.microsoft.com
schemes:
  - https
consumes: []
produces:
  - application/json
  - application/xml
securityDefinitions:
  AADToken:
    type: oauth2
    authorizationUrl: https://login.microsoftonline.com/common/oauth2/authorize
    flow: implicit
    description: >-
      These are the [Microsoft Entra OAuth
      2.0](https://docs.microsoft.com/azure/active-directory/develop/v1-overview)
      Flows. When paired with [Azure role-based
      access](https://docs.microsoft.com/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.


      To 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.


      #### Notes

      * 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).

      * 

      The `Authorization URL` is specific to the Azure public cloud instance.
      Sovereign clouds have unique Authorization URLs and Microsoft Entra ID
      configurations. 

      * 

      The 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.

      * 

      Usage of the [Azure Maps Web SDK](https://aka.ms/amaadmc) allows for
      configuration based setup of an application for multiple use cases.

      * For more information on Microsoft identity platform, see [Microsoft
      identity platform
      overview](https://learn.microsoft.com/entra/identity-platform/v2-overview).
    scopes:
      https://atlas.microsoft.com/.default: https://atlas.microsoft.com/.default
  SharedKey:
    type: apiKey
    description: >-
      This is a shared key that is provisioned when you [Create an Azure Maps
      account](https://docs.microsoft.com/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.

       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.

       For publicly exposed applications, our recommendation is to use the [confidential client applications](https://docs.microsoft.com/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.

       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.

       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
security:
  - AADToken:
      - https://atlas.microsoft.com/.default
  - SharedKey: []
  - SasToken: []
responses:
  '400':
    description: >-
      Bad request: one or more parameters were incorrectly specified or are
      mutually exclusive.
    schema:
      $ref: '#/definitions/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.
    schema:
      $ref: '#/definitions/ODataErrorResponse'
    headers:
      WWW-Authenticate:
        type: string
        description: >-
          Bearer realm="https://atlas.microsoft.com/", error="invalid_token",
          error_description="The access token expired"
  '403':
    description: Permission, capacity, or authentication issues.
    schema:
      $ref: '#/definitions/ODataErrorResponse'
  '404':
    description: >-
      Not Found: the requested resource could not be found, but it may be
      available again in the future.
    schema:
      $ref: '#/definitions/ODataErrorResponse'
  '500':
    description: An error occurred while processing the request. Please try again later.
    schema:
      $ref: '#/definitions/ODataErrorResponse'
parameters:
  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.
    type: string
    in: header
    required: false
    x-ms-parameter-location: client
  SubscriptionKey:
    name: subscription-key
    description: >-
      One of the Azure Maps keys provided from an Azure Map Account. Please
      refer to this
      [article](https://docs.microsoft.com/azure/azure-maps/how-to-manage-authentication)
      for details on how to manage authentication.
    type: string
    in: query
    required: false
    x-ms-parameter-location: client
  ApiVersion:
    name: api-version
    description: Version number of Azure Maps API. Current version is 1.0
    type: string
    in: query
    required: true
    default: '1.0'
    x-ms-parameter-location: client
paths: {}
definitions:
  ODataErrorResponse:
    type: object
    description: >-
      This response object is returned when an error occurs in the Azure Maps
      API.
    properties:
      error:
        $ref: '#/definitions/ODataError'
  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: '#/definitions/ODataError'
      target:
        type: string
        readOnly: true
        description: If available, the target causing the error.
  GeoJSONPosition:
    description: >-
      A valid `GeoJSON Position` geometry type. A `Position` is an array of
      numbers with two or more elements. The first two elements are _longitude_
      and _latitude_, precisely in that order. _Altitude/Elevation_ is an
      optional third element. Please refer to [RFC
      7946](https://tools.ietf.org/html/rfc7946#section-3.1.1) for details.
    type: array
    items:
      type: number
      format: double
  GeoJSONGeometry:
    description: >-
      A valid `GeoJSON` geometry object. Please refer to [RFC
      7946](https://tools.ietf.org/html/rfc7946#section-3.1) for details.
    type: object
    discriminator: type
    required:
      - type
    properties:
      type:
        description: >-
          Specifies the `GeoJSON` geometry type. Must be one of the seven valid
          GeoJSON geometry types - Point, MultiPoint, LineString,
          MultiLineString, Polygon, MultiPolygon and GeometryCollection.
        type: string
        enum:
          - Point
          - MultiPoint
          - LineString
          - MultiLineString
          - Polygon
          - MultiPolygon
          - GeometryCollection
        x-ms-enum:
          name: GeoJSONGeometryType
          modelAsString: true
          values:
            - value: Point
              description: '`GeoJSON Point` geometry.'
            - value: MultiPoint
              description: '`GeoJSON MultiPoint` geometry.'
            - value: LineString
              description: '`GeoJSON LineString` geometry.'
            - value: MultiLineString
              description: '`GeoJSON MultiLineString` geometry.'
            - value: Polygon
              description: '`GeoJSON Polygon` geometry.'
            - value: MultiPolygon
              description: '`GeoJSON MultiPolygon` geometry.'
            - value: GeometryCollection
              description: '`GeoJSON GeometryCollection` geometry.'
  Point:
    description: >-
      A valid `GeoJSON Point` geometry type. Please refer to [RFC
      7946](https://tools.ietf.org/html/rfc7946#section-3.1.2) for details.
    type: object
    allOf:
      - $ref: '#/definitions/GeoJSONGeometry'
      - properties:
          type:
            description: >-
              Specifies the `type` for the geometry. Value should always be
              equal to "Point".
            type: string
          coordinates:
            $ref: '#/definitions/GeoJSONPosition'
        required:
          - coordinates
  GeoJsonBoundingBox:
    description: |-
      Bounding Box. The bounding box is an array of length 2*n where n is
      the number of dimensions represented in the contained geometries,
      with all axes of the most southwesterly point followed by all axes
      of the more northeasterly point.  The axes order of a bbox follows
      the axes order of geometries.

      The edges of the bounding box follow lines of constant longitude,
      latitude, and elevation.
    type: array
    items:
      type: number
      format: double
  Geometry:
    description: >-
      This represents the geometry for one or more geographical features (parks,
      state boundary etc.) and should be a `GeoJSON` compliant type. Please
      refer to [RFC 7946](https://tools.ietf.org/html/rfc7946) for details.
    type: object
  FeedbackStatusResponse:
    type: object
    required:
      - formatVersion
      - feedbackId
      - status
      - createDate
      - featureType
      - action
      - request
    properties:
      formatVersion:
        type: string
      feedbackId:
        type: string
      status:
        type: string
      createDate:
        type: string
      featureType:
        type: string
      action:
        type: string
      request:
        description: The original request object.
        type: object
  FeedbackAddPoiRequestBody:
    type: object
    required:
      - location
      - bbox
      - feature
    properties:
      isMock:
        type: boolean
      location:
        $ref: '#/definitions/GeoJSONPosition'
      bbox:
        $ref: '#/definitions/GeoJsonBoundingBox'
      comments:
        type: string
      contactInformation:
        $ref: '#/definitions/FeedbackContactInformation'
      feature:
        $ref: '#/definitions/FeedbackPoiFeature'
  FeedbackFixPoiRequestBody:
    type: object
    required:
      - location
      - bbox
      - feature
    properties:
      isMock:
        type: boolean
      location:
        $ref: '#/definitions/GeoJSONPosition'
      bbox:
        $ref: '#/definitions/GeoJsonBoundingBox'
      comments:
        type: string
      contactInformation:
        $ref: '#/definitions/FeedbackContactInformation'
      feature:
        $ref: '#/definitions/FeedbackPoiUpdateFeature'
  FeedbackDeletePoiRequestBody:
    type: object
    required:
      - location
      - bbox
      - feature
    properties:
      isMock:
        type: boolean
      location:
        $ref: '#/definitions/GeoJSONPosition'
      bbox:
        $ref: '#/definitions/GeoJsonBoundingBox'
      comments:
        type: string
      contactInformation:
        $ref: '#/definitions/FeedbackContactInformation'
      feature:
        $ref: '#/definitions/FeedbackPoiFeature'
  FeedbackPoiFeature:
    type: object
    required:
      - name
      - category
      - geometry
    properties:
      featureId:
        type: string
      name:
        type: string
      category:
        type: string
      subcategory:
        type: string
      emailAddress:
        type: string
      faxNumber:
        type: string
      telephoneNumber:
        type: string
      website:
        type: string
      houseNumber:
        type: string
      streetName:
        type: string
      city:
        type: string
      postCode:
        type: string
      stateName:
        type: string
      country:
        type: string
      geometry:
        $ref: '#/definitions/Point'
  FeedbackPoiUpdateFeature:
    type: object
    required:
      - name
      - category
      - geometry
    properties:
      featureId:
        type: string
      name:
        $ref: '#/definitions/FeedbackStringFieldUpdate'
      category:
        $ref: '#/definitions/FeedbackStringFieldUpdate'
      subcategory:
        $ref: '#/definitions/FeedbackStringFieldUpdate'
      emailAddress:
        $ref: '#/definitions/FeedbackStringFieldUpdate'
      faxNumber:
        $ref: '#/definitions/FeedbackStringFieldUpdate'
      telephoneNumber:
        $ref: '#/definitions/FeedbackStringFieldUpdate'
      website:
        $ref: '#/definitions/FeedbackStringFieldUpdate'
      houseNumber:
        $ref: '#/definitions/FeedbackStringFieldUpdate'
      streetName:
        $ref: '#/definitions/FeedbackStringFieldUpdate'
      city:
        $ref: '#/definitions/FeedbackStringFieldUpdate'
      postCode:
        $ref: '#/definitions/FeedbackStringFieldUpdate'
      stateName:
        $ref: '#/definitions/FeedbackStringFieldUpdate'
      country:
        $ref: '#/definitions/FeedbackStringFieldUpdate'
      geometry:
        $ref: '#/definitions/FeedbackGeometryFieldUpdate'
  FeedbackAddAddressRequestBody:
    type: object
    required:
      - location
      - bbox
      - feature
    properties:
      isMock:
        type: boolean
      location:
        $ref: '#/definitions/GeoJSONPosition'
      bbox:
        $ref: '#/definitions/GeoJsonBoundingBox'
      comments:
        type: string
      contactInformation:
        $ref: '#/definitions/FeedbackContactInformation'
      feature:
        $ref: '#/definitions/FeedbackAddressFeature'
  FeedbackFixAddressRequestBody:
    type: object
    required:
      - location
      - bbox
      - feature
    properties:
      isMock:
        type: boolean
      location:
        $ref: '#/definitions/GeoJSONPosition'
      bbox:
        $ref: '#/definitions/GeoJsonBoundingBox'
      comments:
        type: string
      contactInformation:
        $ref: '#/definitions/FeedbackContactInformation'
      feature:
        $ref: '#/definitions/FeedbackAddressUpdateFeature'
  FeedbackDeleteAddressRequestBody:
    type: object
    required:
      - location
      - bbox
      - feature
    properties:
      isMock:
        type: boolean
      location:
        $ref: '#/definitions/GeoJSONPosition'
      bbox:
        $ref: '#/definitions/GeoJsonBoundingBox'
      comments:
        type: string
      contactInformation:
        $ref: '#/definitions/FeedbackContactInformation'
      feature:
        $ref: '#/definitions/FeedbackAddressFeature'
  FeedbackAddressFeature:
    type: object
    required:
      - houseNumber
      - streetName
      - city
      - postCode
      - geometry
    properties:
      featureId:
        type: string
      houseNumber:
        type: string
      streetName:
        type: string
      city:
        type: string
      postCode:
        type: string
      stateName:
        type: string
      country:
        type: string
      geometry:
        $ref: '#/definitions/Point'
  FeedbackAddressUpdateFeature:
    type: object
    required:
      - houseNumber
      - streetName
      - city
      - postCode
      - geometry
    properties:
      featureId:
        type: string
      houseNumber:
        $ref: '#/definitions/FeedbackStringFieldUpdate'
      streetName:
        $ref: '#/definitions/FeedbackStringFieldUpdate'
      city:
        $ref: '#/definitions/FeedbackStringFieldUpdate'
      postCode:
        $ref: '#/definitions/FeedbackStringFieldUpdate'
      stateName:
        $ref: '#/definitions/FeedbackStringFieldUpdate'
      country:
        $ref: '#/definitions/FeedbackStringFieldUpdate'
      geometry:
        $ref: '#/definitions/FeedbackGeometryFieldUpdate'
  FeedbackFixOtherRequestBody:
    type: object
    required:
      - location
      - bbox
    properties:
      isMock:
        type: boolean
      location:
        $ref: '#/definitions/GeoJSONPosition'
      bbox:
        $ref: '#/definitions/GeoJsonBoundingBox'
      comments:
        type: string
      contactInformation:
        $ref: '#/definitions/FeedbackContactInformation'
  FeedbackContactInformation:
    type: object
    properties:
      emailAddress:
        type: string
  FeedbackStringFieldUpdate:
    type: object
    properties:
      current:
        type: string
      proposed:
        type: string
  FeedbackGeometryFieldUpdate:
    type: object
    properties:
      current:
        $ref: '#/definitions/Geometry'
      proposed:
        $ref: '#/definitions/Geometry'