openapi: 3.2.0
info:
  title: Interactive Map API v1 Write Features API
  description: Interactive Map API v1 is a REST API for simple access to geo data.
  contact: {}
  version: 1.22.2
  x-olp-service:
    name: interactive
    version: v1
servers:
- url: https://use.apilookup.for.a.base.url/
security:
- Bearer: []
tags:
- name: Write Features
  description: Write endpoints for features.
paths:
  /layers/{layerId}/features:
    put:
      tags:
      - Write Features
      summary: Create or replace multiple features
      description: Create or replace the provided features.
      operationId: Interactive Map API v1 putFeatures
      parameters:
      - $ref: '#/components/parameters/LayerId'
      - $ref: '#/components/parameters/VersionRef'
      requestBody:
        $ref: '#/components/requestBodies/FeatureCollectionRequest'
      responses:
        '200':
          $ref: '#/components/responses/FeatureCollectionModificationResponse'
        '204':
          $ref: '#/components/responses/EmptyResponse'
        '400':
          $ref: '#/components/responses/ErrorResponse400'
        '401':
          $ref: '#/components/responses/ErrorResponse401'
        '403':
          $ref: '#/components/responses/ErrorResponse403'
        '404':
          $ref: '#/components/responses/ErrorResponse404'
        '409':
          $ref: '#/components/responses/ErrorResponse409'
        '413':
          $ref: '#/components/responses/ErrorResponse413'
        '513':
          $ref: '#/components/responses/ErrorResponse513'
      x-olp-access-type: resource
    post:
      tags:
      - Write Features
      summary: Modify features in the layer
      description: Create or patch features.
      operationId: Interactive Map API v1 postFeatures
      parameters:
      - $ref: '#/components/parameters/LayerId'
      - $ref: '#/components/parameters/VersionRef'
      requestBody:
        $ref: '#/components/requestBodies/FeatureCollectionOrFeatureModificationListRequest'
      responses:
        '200':
          $ref: '#/components/responses/FeatureCollectionModificationResponse'
        '204':
          $ref: '#/components/responses/EmptyResponse'
        '400':
          $ref: '#/components/responses/ErrorResponse400'
        '401':
          $ref: '#/components/responses/ErrorResponse401'
        '403':
          $ref: '#/components/responses/ErrorResponse403'
        '404':
          $ref: '#/components/responses/ErrorResponse404'
        '409':
          $ref: '#/components/responses/ErrorResponse409'
        '413':
          $ref: '#/components/responses/ErrorResponse413'
        '513':
          $ref: '#/components/responses/ErrorResponse513'
      x-olp-access-type: resource
    delete:
      tags:
      - Write Features
      summary: Delete multiple features
      description: Delete the features with the provided ids.
      operationId: Interactive Map API v1 deleteFeatures
      parameters:
      - $ref: '#/components/parameters/LayerId'
      - $ref: '#/components/parameters/Ids'
      - $ref: '#/components/parameters/VersionRef'
      - name: eraseContent
        in: query
        description: 'false - [default]


          true  - erase, wipe all content'
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          $ref: '#/components/responses/FeatureCollectionModificationResponse'
        '204':
          $ref: '#/components/responses/EmptyResponse'
        '401':
          $ref: '#/components/responses/ErrorResponse401'
        '403':
          $ref: '#/components/responses/ErrorResponse403'
        '404':
          $ref: '#/components/responses/ErrorResponse404'
      x-olp-access-type: resource
  /layers/{layerId}/features/{featureId}:
    put:
      tags:
      - Write Features
      summary: Create or replace a feature
      description: Creates or replaces a feature in the layer.
      operationId: Interactive Map API v1 putFeature
      parameters:
      - $ref: '#/components/parameters/LayerId'
      - $ref: '#/components/parameters/FeatureId'
      - $ref: '#/components/parameters/VersionRef'
      requestBody:
        $ref: '#/components/requestBodies/FeatureRequest'
      responses:
        '200':
          $ref: '#/components/responses/FeatureResponse'
        '400':
          $ref: '#/components/responses/ErrorResponse400'
        '401':
          $ref: '#/components/responses/ErrorResponse401'
        '403':
          $ref: '#/components/responses/ErrorResponse403'
        '409':
          $ref: '#/components/responses/ErrorResponse409'
        '413':
          $ref: '#/components/responses/ErrorResponse413'
        '513':
          $ref: '#/components/responses/ErrorResponse513'
      x-olp-access-type: resource
    patch:
      tags:
      - Write Features
      summary: Patch a feature
      description: Patches an existing feature.
      operationId: Interactive Map API v1 patchFeature
      parameters:
      - $ref: '#/components/parameters/LayerId'
      - $ref: '#/components/parameters/FeatureId'
      - $ref: '#/components/parameters/VersionRef'
      requestBody:
        $ref: '#/components/requestBodies/FeatureRequest'
      responses:
        '200':
          $ref: '#/components/responses/FeatureResponse'
        '400':
          $ref: '#/components/responses/ErrorResponse400'
        '401':
          $ref: '#/components/responses/ErrorResponse401'
        '403':
          $ref: '#/components/responses/ErrorResponse403'
        '404':
          $ref: '#/components/responses/ErrorResponse404'
        '409':
          $ref: '#/components/responses/ErrorResponse409'
        '413':
          $ref: '#/components/responses/ErrorResponse413'
        '513':
          $ref: '#/components/responses/ErrorResponse513'
      x-olp-access-type: resource
    delete:
      tags:
      - Write Features
      summary: Deletes a feature from the layer
      description: Deletes an existing feature.
      operationId: Interactive Map API v1 deleteFeature
      parameters:
      - $ref: '#/components/parameters/LayerId'
      - $ref: '#/components/parameters/FeatureId'
      - $ref: '#/components/parameters/VersionRef'
      responses:
        '204':
          $ref: '#/components/responses/EmptyResponse'
        '401':
          $ref: '#/components/responses/ErrorResponse401'
        '403':
          $ref: '#/components/responses/ErrorResponse403'
        '404':
          $ref: '#/components/responses/ErrorResponse404'
      x-olp-access-type: resource
components:
  responses:
    ErrorResponse413:
      description: Request entity too large.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            type: ErrorResponse
            error: Exception
            errorMessage: Request entity too large.
            streamId: 7480e28a-e273-11e8-9af8-7508bbe361d9
      headers:
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
    ErrorResponse400:
      description: Malformed or Bad Request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            type: ErrorResponse
            streamId: 7480e28a-e273-11e8-9af8-7508bbe361d9
            error: Exception
            errorMessage: <Invalid request details>
      headers:
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
    FeatureResponse:
      description: A feature response.
      content:
        application/geo+json:
          schema:
            $ref: '#/components/schemas/Feature'
      headers:
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
    ErrorResponse403:
      description: Forbidden request. Insufficient rights to perform the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            type: ErrorResponse
            streamId: 7480e28a-e273-11e8-9af8-7508bbe361d9
            error: Exception
            errorMessage: Insufficient rights + <Request specific access error details>
    EmptyResponse:
      description: An empty response as a result of a user-request with accepted MIME type application/x-empty.
      content:
        application/x-empty:
          schema:
            type: string
      headers:
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
    FeatureCollectionModificationResponse:
      description: An array of features and their modifications response.
      content:
        application/geo+json:
          schema:
            $ref: '#/components/schemas/FeatureCollectionModification'
          example:
            type: FeatureCollection
            etag: b9be03f253c53c23
            inserted:
            - BfiimUxHjj
            updated:
            - cuiImUxOjj
            features:
            - type: Feature
              id: BfiimUxHjj
              geometry:
                type: Point
                coordinates:
                - -2.960847
                - 53.430828
              properties:
                name: Anfield
                '@ns:com:here:xyz':
                  createdAt: 1517504700726
                  updatedAt: 1517504700726
                amenity: Football Stadium
                capacity: 54074
                description: Home of the Liverpool Football Club.
      headers:
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
    ErrorResponse409:
      description: An error response which indicates a conflict.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            type: ErrorResponse
            streamId: 7480e28a-e273-11e8-9af8-7508bbe361d9
            error: Exception
            errorMessage: The record exists.
      headers:
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
    ErrorResponse513:
      description: Response payload too large.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            type: ErrorResponse
            streamId: 7480e28a-e273-11e8-9af8-7508bbe361d9
            error: Exception
            errorMessage: The response payload was too large. Please try to reduce the expected amount of data.
      headers:
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
    ErrorResponse404:
      description: Not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            type: ErrorResponse
            streamId: 7480e28a-e273-11e8-9af8-7508bbe361d9
            error: Exception
            errorMessage: The requested resource does not exist.
      headers:
        X-Correlation-ID:
          $ref: '#/components/headers/X-Correlation-ID'
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
    ErrorResponse401:
      description: Unauthorized to perform the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  headers:
    X-Correlation-ID:
      description: Auto-generated ID, which uniquely identifies the request, available in the response. When contacting support with an inquiry regarding a specific request, provide the value of this header which will help troubleshooting the issue.
      schema:
        type: string
      example: 4199533b-6290-41db-8d79-edf4f4019a74
    X-Request-ID:
      description: User-provided token that can be used to trace a request or a group of requests sent to the service.
      schema:
        type: string
  requestBodies:
    FeatureCollectionOrFeatureModificationListRequest:
      description: A FeatureCollection object or a FeatureModificationList object.
      required: true
      content:
        application/geo+json:
          schema:
            $ref: '#/components/schemas/FeatureCollection'
        application/vnd.here.feature-modification-list:
          schema:
            $ref: '#/components/schemas/FeatureModificationList'
    FeatureCollectionRequest:
      description: A feature collection request.
      required: true
      content:
        application/geo+json:
          schema:
            $ref: '#/components/schemas/FeatureCollection'
    FeatureRequest:
      description: A feature request.
      required: true
      content:
        application/geo+json:
          schema:
            $ref: '#/components/schemas/Feature'
  schemas:
    OnFeatureNotExists:
      type: string
      enum:
      - retain
      - error
      - create
      default: create
    OnMergeConflict:
      type: string
      enum:
      - error
      - retain
      - replace
      default: error
    FeatureCollection:
      allOf:
      - $ref: '#/components/schemas/GeoJSON'
      - type: object
        description: A FeatureCollection GeoJSON object.
        required:
        - features
        discriminator:
          propertyName: type
          mapping:
            FeatureCollectionIterable: '#/components/schemas/FeatureCollectionIterable'
            FeatureCollectionModification: '#/components/schemas/FeatureCollectionModification'
        properties:
          features:
            type: array
            description: Features included in the collection.
            items:
              $ref: '#/components/schemas/Feature'
        example:
          type: FeatureCollection
          features:
          - type: Feature
            id: BfiimUxHjj
            geometry:
              type: Point
              coordinates:
              - -2.960847
              - 53.430828
            properties:
              name: Anfield
              '@ns:com:here:xyz':
                createdAt: 1517504700726
                updatedAt: 1517504700726
              amenity: Football Stadium
              capacity: 54074
              description: Home of the Liverpool Football Club.
    OnFeatureExists:
      type: string
      enum:
      - merge
      - patch
      - replace
      - delete
      - retain
      - error
      default: patch
    Feature:
      allOf:
      - $ref: '#/components/schemas/GeoJSON'
      - type: object
        description: A Feature object represents a spatially bounded thing.
        properties:
          id:
            description: The unique identifier of the feature.
            type: string
          geometry:
            $ref: '#/components/schemas/Geometry'
          properties:
            type: object
            description: The properties of the feature.
            additionalProperties: true
        example:
          type: Feature
          id: BfiimUxHjj
          geometry:
            type: Point
            coordinates:
            - -2.960847
            - 53.430828
          properties:
            name: Anfield
            amenity: Football Stadium
            capacity: 54074
            description: Home of the Liverpool Football Club.
    FeatureCollectionModification:
      allOf:
      - $ref: '#/components/schemas/FeatureCollection'
      - type: object
        properties:
          inserted:
            type: array
            description: List of inserted feature IDs.
            items:
              type: string
          updated:
            type: array
            description: List of updated features IDs.
            items:
              type: string
          deleted:
            type: array
            description: List of deleted features IDs.
            items:
              type: string
        example:
          type: FeatureCollection
          etag: b9be03f253c53c23
          inserted:
          - BfiimUxHjj
          updated:
          - cuiImUxOjj
          features:
          - type: Feature
            id: BfiimUxHjj
            geometry:
              type: Point
              coordinates:
              - -2.960847
              - 53.430828
            properties:
              name: Anfield
              '@ns:com:here:xyz':
                createdAt: 1517504700726
                updatedAt: 1517504700726
                space: 0FzlE2wX
              amenity: Football Stadium
              capacity: 54074
              description: Home of the Liverpool Football Club.
    FeatureModification:
      type: object
      description: 'A FeatureModification object containing GeoJSON FeatureCollections

        (see [RFC-7946](https://tools.ietf.org/html/rfc7946)) or (in case if deletions) a list of

        feature IDs.

        '
      required:
      - type
      properties:
        type:
          type: string
        featureData:
          $ref: '#/components/schemas/FeatureCollection'
        featureIds:
          type: array
          description: A list of feature IDs (strings)
          items:
            type: string
        onFeatureNotExists:
          $ref: '#/components/schemas/OnFeatureNotExists'
        onFeatureExists:
          $ref: '#/components/schemas/OnFeatureExists'
        onMergeConflict:
          $ref: '#/components/schemas/OnMergeConflict'
      example:
        type: FeatureModification
        featureData:
          type: FeatureCollection
          features:
          - type: Feature
            id: BfiimUxHjj
            geometry:
              type: Point
              coordinates:
              - -2.960847
              - 53.430828
            properties:
              name: Anfield
              amenity: Football Stadium
              capacity: 54074
              description: Home of the Liverpool Football Club.
    Geometry:
      allOf:
      - $ref: '#/components/schemas/GeoJSON'
      - type: object
        description: A Geometry object represents points, curves, and surfaces in coordinate layer.
        discriminator:
          propertyName: type
          mapping:
            MultiPoint: '#/components/schemas/MultiPoint'
            MultiLineString: '#/components/schemas/MultiLineString'
            LineString: '#/components/schemas/LineString'
            MultiPolygon: '#/components/schemas/MultiPolygon'
            Point: '#/components/schemas/Point'
            Polygon: '#/components/schemas/Polygon'
    Error:
      type: object
      description: The response send when the request failed. This response may be send for certain HTTP error codes like 403 Forbidden or 502 Bad Gateway and should hold more details about the error reason.
      properties:
        title:
          type: string
          description: Human-readable error description
          example: Input data failed validation
        status:
          type: integer
          description: HTTP status code
          example: 400
        code:
          type: string
          description: Error code.
          example: Bad Request
        cause:
          type: string
          description: Human-readable explanation for the error
          example: The input data in question does not comply with validation rules
        action:
          type: string
          description: Human-readable description of the action that can be taken to correct the error
          example: Request a valid id
        correlationId:
          type: string
          description: Auto-generated id that uniquely identifies the request
          example: 4199533b-6290-41db-8d79-edf4f4019a74
    GeoJSON:
      type: object
      description: The base type for all possible GeoJSON objects.
      required:
      - type
      properties:
        type:
          type: string
        bbox:
          type: array
          description: Describes the coordinate range of the GeoJSON object.
          items:
            type: number
      discriminator:
        propertyName: type
        mapping:
          Feature: '#/components/schemas/Feature'
          FeatureCollection: '#/components/schemas/FeatureCollection'
          Geometry: '#/components/schemas/Geometry'
      additionalProperties: true
    FeatureModificationList:
      type: object
      description: 'An object describing modifications of features. Contains feature data being provided as

        GeoJSON FeatureCollections (see [RFC-7946](https://tools.ietf.org/html/rfc7946))

        or (in case of deletions) a list of feature IDs.

        '
      externalDocs:
        url: https://tools.ietf.org/html/rfc7946
      required:
      - type
      properties:
        type:
          type: string
        modifications:
          type: array
          description: A list of FeatureModification objects
          items:
            $ref: '#/components/schemas/FeatureModification'
      example:
        type: FeatureModificationList
        modifications:
        - type: FeatureModification
          featureData:
            type: FeatureCollection
            features:
            - type: Feature
              id: BfiimUxHjj
              geometry:
                type: Point
                coordinates:
                - -2.960847
                - 53.430828
              properties:
                name: Anfield
                amenity: Football Stadium
                capacity: 54074
                description: Home of the Liverpool Football Club.
  parameters:
    VersionRef:
      name: versionRef
      in: query
      description: "The query parameter used to specify the target version reference when reading or writing features.\nA reference describes a target tag or a version.\n\nDefault is: `HEAD`\n\n<br>\nDepending on the use-case it can be necessary to specify a range of versions rather than\nonly one version. In such a case the version part of the Ref would look like:\n`<start>..<end>`\n\nWhere `<start>` is the start of the range (exclusive) and `<end>` is the end of the range\n(inclusive).\n\nAnother way of specifying a version range is using the star-symbol: `*`\n\nUsing `*` refers to \"all available versions\" in the space or branch and is only\napplicable in the cases in which a version range may be provided.\n\n<br>\nSamples:\n  - `42` points to version 42\n  - `HEAD` points to the latest version\n  - `myTag` points to the version of the tag with ID \"myTag\"\n  - `0..HEAD` points to all available versions\n  - `*` also points to all versions (short form)\n  - `5..10` points to the versions in the interval `]5, 10]`\n"
      required: false
      schema:
        type: string
        default: HEAD
    LayerId:
      name: layerId
      in: path
      description: The unique identifier of the layer.
      required: true
      schema:
        type: string
    Ids:
      name: id
      in: query
      description: "A comma separated list of unique feature identifiers. These are the acceptable formats for this field:\n  * id=value1,value2\n  * id=value1,id=value2\n\n\nnot required when eraseContent=true is used."
      required: false
      schema:
        type: array
        items:
          type: string
    FeatureId:
      name: featureId
      in: path
      description: The unique identifier of a feature in the layer.
      required: true
      schema:
        type: string
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'A token obtained from a separate endpoint using client credentials and an OAuth 1.0a HMAC-SHA256 signed request.


        For more information on how to get a bearer token, see the [Identity & Access Management Guide](https://developer.here.com/documentation/identity-access-management/dev_guide/index.html).

        '
    ApiKey:
      type: apiKey
      in: query
      name: apiKey
      description: 'A key generated specifically to authenticate API requests. For more information on how to get an API key, see the [Identity & Access Management Guide](https://developer.here.com/documentation/identity-access-management/dev_guide/index.html).

        '
externalDocs:
  description: The developer guide and related API references are available here.
  url: https://www.here.com/docs/category/data-api