HERE Query API

openapi: 3.2.0
info:
  title: v1 Query API
  description: The `query` service provides a way to get information (metadata) about layers and partitions stored in a catalog. This service exposes the metadata for single partitions that users can query one by one or by specifying a parent tile.
  contact: {}
  version: 1.0.4
  x-olp-service:
    name: query
    version: v1
servers:
- url: https://use.apilookup.for.a.base.url/
security:
- Bearer: []
tags:
- name: Query
  description: Get metadata for catalogs, partitions, and indexes
paths:
  /layers/{layerId}/changes:
    get:
      tags:
      - Query
      summary: Gets changes for the version or time range for the specific partition(s)
      description: Gets the latest partition changes for a version range in a versioned layer or a time range for a volatile layer. Only the latest change for each changed partition is returned, not intermediate changes. If the response contains a partition with an empty 'dataHandle' value, the partition was deleted at the version indicated by the 'version' field of the partition object. If a partition was created and deleted between the versions specified in the `startVersion` and `endVersion` parameters, the partition is included in the response with an empty `dataHandle` value. For example, if you request versions `0` to `10`, and a partition was created in version `3` and then deleted in version `7`, it is included in the response with an empty `dataHandle` value.
      operationId: Query API v1 getChangesById
      parameters:
      - name: layerId
        in: path
        description: The ID of the layer specified in the request. The value of this parameter must refer to a valid layer already configured in the catalog configuration. You can specify multiple layers as additional parameters.
        required: true
        schema:
          type: string
      - name: startVersion
        in: query
        description: Start version for the catalog (exclusive). By convention -1 indicates the virtual initial version before the first publication which will have version 0.
        schema:
          type: string
      - name: endVersion
        in: query
        description: End version (inclusive). This has to be a valid catalog version greater than the startVersion.
        schema:
          type: string
      - name: sinceTime
        in: query
        description: Will return partitions whose data has been modified since this time, in milliseconds since epoch, inclusive.
        schema:
          type: integer
          format: int64
      - $ref: '#/components/parameters/Context'
      - name: additionalFields
        in: query
        description: Additional fields - `dataSize`, `checksum`, `compressedDataSize`, `crc`.
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
            enum:
            - dataSize
            - checksum
            - compressedDataSize
            - crc
      - name: partition
        in: query
        description: The partitions you want to include in the response. This allows you to limit the response to specific partitions. You can specify multiple partitions by using this parameter multiple times. The maximum number of partitions per call is 100.
        required: true
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: billingTag
        in: query
        description: Billing Tag is an optional free-form tag which is used for grouping billing records together. If supplied, it must be between 4 - 16 characters, contain only alpha/numeric ASCII characters  [A-Za-z0-9]. Grouping billing records by billing tag will be available in future releases.
        schema:
          type: string
      responses:
        '200':
          description: OK
          headers:
            Last-Modified:
              description: For volatile layers, contains the latest date and time at which a returned partition's data was modified.
              schema:
                type: string
                format: date-time
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Partitions'
        '400':
          description: Required parameters are missing
          content: {}
        '401':
          description: Unauthorized
          content: {}
        '403':
          description: Forbidden
          content: {}
        '404':
          description: Catalog or layer does not exist
          content: {}
      x-olp-access-type: resource
  /layers/{layerId}/partitions:
    get:
      tags:
      - Query
      summary: Gets metadata for the requested partitions
      description: Gets metadata for specific partition ids. If the layer specified in the request does not exist, the request results in an error. If a partition specified in the request does not exist, the response does not include this partition. Maximum allowed number of partitions ids per call is 100.
      operationId: Query API v1 getPartitionsById
      parameters:
      - name: layerId
        in: path
        description: The ID of the layer specified in the request. The content of this parameter must refer to a valid layer already configured in the catalog configuration. You can specify multiple partitions by using this parameter multiple times.
        required: true
        schema:
          type: string
      - name: partition
        in: query
        description: Partition ids to use for filtering. You can specify multiple partitions by using this parameter multiple times. Maximum allowed partitions ids per call is 100.
        required: true
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: version
        in: query
        description: The version of the catalog against which to run the query. Must be a valid catalog version.
        schema:
          type: string
      - $ref: '#/components/parameters/Context'
      - name: additionalFields
        in: query
        description: Additional fields - `dataSize`, `checksum`, `compressedDataSize`, `crc`.
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
            enum:
            - dataSize
            - checksum
            - compressedDataSize
            - crc
      - name: billingTag
        in: query
        description: Billing Tag is an optional free-form tag which is used for grouping billing records together. If supplied, it must be between 4 - 16 characters, contain only alpha/numeric ASCII characters  [A-Za-z0-9]. Grouping billing records by billing tag will be available in future releases.
        schema:
          type: string
      responses:
        '200':
          description: OK - Your search for partitions is a valid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Partitions'
        '400':
          description: Required parameters are missing
          content: {}
        '401':
          description: Unauthorized
          content: {}
        '403':
          description: Forbidden
          content: {}
        '404':
          description: Catalog or layer does not exist
          content: {}
      x-olp-access-type: resource
  /layers/{layerId}/versions/{version}/quadkeys/{quadKey}/depths/{depth}:
    get:
      tags:
      - Query
      summary: Gets index metadata of versioned
      description: Gets metadata for the requested index. Only available for versioned layers where the partitioning scheme is `heretile`.
      operationId: Query API v1 quadTreeIndex
      parameters:
      - name: layerId
        in: path
        description: The ID of the layer specified in the request. Content of this parameter must refer to a valid layer already configured in the catalog configuration. Exactly one layer ID must be provided.
        required: true
        schema:
          type: string
      - name: version
        in: path
        description: The version of the catalog against which to run the query. Must be a valid catalog version.
        required: true
        schema:
          type: integer
          format: int64
      - name: quadKey
        in: path
        description: The geometric area specified by an index in the request, represented as a HERE tile
        required: true
        schema:
          type: string
      - name: depth
        in: path
        description: The recursion depth of the response. If set to 0, the response includes only data for the quadKey specified in the request. In this way, depth describes the maximum length of the subQuadKeys in the response. The maximum allowed value for the depth parameter is 4.
        required: true
        schema:
          type: integer
          format: int32
      - $ref: '#/components/parameters/Context'
      - name: additionalFields
        in: query
        description: Additional fields - `dataSize`, `checksum`, `compressedDataSize`, `crc`.
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
            enum:
            - dataSize
            - checksum
            - compressedDataSize
            - crc
      - name: billingTag
        in: query
        description: Billing Tag is an optional free-form tag used to group billing records together. If supplied, it must be between 4 - 16 characters and  contain only alphanumeric ASCII characters  [A-Za-z0-9]. Grouping billing records by billing tag will be available in a future release.
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Index'
        '400':
          description: Required parameters are missing
          content: {}
        '401':
          description: Unauthorized
          content: {}
        '403':
          description: Forbidden
          content: {}
        '404':
          description: Not Found
          content: {}
      x-olp-access-type: resource
  /layers/{layerId}/quadkeys/{quadKey}/depths/{depth}:
    get:
      tags:
      - Query
      summary: Gets index metadata for volatile layers
      description: Gets metadata for the requested index. Only available for volatile layers where the partitioning scheme is `heretile`.
      operationId: Query API v1 quadTreeIndexVolatile
      parameters:
      - name: layerId
        in: path
        description: The ID of the layer specified in the request. Content of this parameter must refer to a valid layer already configured in the catalog configuration. Exactly one layer ID must be provided.
        required: true
        schema:
          type: string
      - name: quadKey
        in: path
        description: The geometric area specified by an index in the request, represented as a HERE tile
        required: true
        schema:
          type: string
      - name: depth
        in: path
        description: The recursion depth of the response. If set to 0, the response includes only data for the quadKey specified in the request. In this way, depth describes the maximum length of the subQuadKeys in the response. The maximum allowed value for the depth parameter is 4.
        required: true
        schema:
          type: integer
          format: int32
      - name: additionalFields
        in: query
        description: Additional fields - `dataSize`, `checksum`, `compressedDataSize`, `crc`.
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
            enum:
            - dataSize
            - checksum
            - compressedDataSize
            - crc
      - name: billingTag
        in: query
        description: Billing Tag is an optional free-form tag used to group billing records together. If supplied, it must be between 4 - 16 characters and  contain only alphanumeric ASCII characters  [A-Za-z0-9]. Grouping billing records by billing tag will be available in a future release.
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Index'
        '400':
          description: Required parameters are missing
          content: {}
        '401':
          description: Unauthorized
          content: {}
        '403':
          description: Forbidden
          content: {}
        '404':
          description: Not Found
          content: {}
      x-olp-access-type: resource
components:
  schemas:
    Partitions:
      required:
      - partitions
      type: object
      properties:
        partitions:
          type: array
          items:
            $ref: '#/components/schemas/Partition'
      description: Describes a list of partitions for a given layer and layer version.
    SubQuad:
      required:
      - dataHandle
      - subQuadKey
      - version
      type: object
      properties:
        additionalMetadata:
          type: string
          description: Optional value for the additional meta-data specified by the publisher.
          example: <Additional metadata>
        checksum:
          type: string
          example: 291f66029c232400e3403cd6e9cfd36e
          description: The checksum field is optional. The response only includes this information if you specify checksum in the request (using `additionalFields` query parameter), and if the request for the commit of the partition  a checksum was provided during commit of the partition. The algorithm used to calculate the checksum is user-specific. Algorithms that you can use are, for example, MD5 or SHA1. The algorithm is defined in the layer configuration. And if it is not defined in the catalog configuration, consumers cannot make any assumptions on the algorithm that was used to calculate the checksum. You need to use the checksum of the data content if you want data comparison working for this catalog. The maximum length of checksum field is 128 characters.
        compressedDataSize:
          type: integer
          description: Optional value for the size of the compressed partition data in bytes. Compressed size of the data when using Blob API in the data client with compression enabled to commit to Data Service.  The response only includes this information if you specify the compressedDataSize field in the request, and if the request for the commit of the partition specifies compressedDataSize.
          format: int64
          example: 200
        dataHandle:
          type: string
          description: To store data in the directly dataHandle, use the `data` URL scheme (RFC 2397). The dataHandle must not contain any characters that are not part of the reserved and unreserved set as defined in RFC3986. This field can have an empty value. When comparing two versions and if the dataHandle is not present, the partition was deleted. The maximum length of dataHandle is 1024 characters.
          example: 1b2ca68f-d4a0-4379-8120-cd025640510c
        dataSize:
          type: integer
          description: Optional value for the size of the partition data in bytes. Uncompressed size of the data when using Blob API in the data client with compression enabled or disabled to commit to Data Service. The response only includes this information if you specify the dataSize field in the requested, and if the request for the commit of the partition specifies dataSize.
          format: int64
          example: 1024
        crc:
          type: string
          description: Optional value for the CRC of the partition data in bytes. The response only includes the data size if you specify `crc` in the `additionalFields` query parameter, and if `crc` was specified in the partition metadata when it was published.
          example: c3f276d7
        subQuadKey:
          type: string
          description: Variable length string defining the child of the passed in quadKey tile. Depending on the partitioning scheme of the layer, either a `quadtree` (deprecated) or a `heretile` formatted id from the sub quad will be returned. When the quadKey is referenced in the response (e.g. when depth is 0), subQuadKey is an empty string for `quadtree` partitioning, and `1` for `heretile` partitioning.
          example: 1
        version:
          type: integer
          description: Version of the catalog when this partition was first published.
          format: int64
          example: 1
    ParentQuad:
      required:
      - dataHandle
      - partition
      - version
      type: object
      properties:
        additionalMetadata:
          type: string
          description: Optional value for the additional metadata specified by the publisher
          example: <Additional metadata>
        checksum:
          type: string
          description: The checksum field is optional. The response includes the checksum only if you specify `checksum` in the `additionalFields` query parameter, and if a checksum was specified in the partition metadata when it was published. The algorithm used to calculate the checksum is user-specific. Algorithms that you can use are, for example, MD5 or SHA1. The algorithm is defined in the layer configuration. And if it is not defined in the catalog configuration, consumers cannot make any assumptions on the algorithm that was used to calculate the checksum. You need to use the checksum of the data content if you want data comparison working for this catalog. The maximum length of the checksum field is 128 characters.
          example: 291f66029c232400e3403cd6e9cfd36e
        compressedDataSize:
          type: integer
          description: Optional value for the size of the compressed partition data in bytes. The response only includes the compressed data size if you specify `compressedDataSize` in the `additionalFields` query parameter, and if compression is enabled, and if `compressedDataSize` was specified in the partition metadata when it was published.
          format: int64
        dataHandle:
          type: string
          description: The dataHandle must not contain any characters that are not part of the reserved and unreserved set as defined in RFC3986. This field must not have an empty value. If the dataHandle is not present when comparing two versions, the partition was deleted. The maximum length of dataHandle is 1024 characters.
          example: 675911FF6236B7C7604BF8B105F1BB58
        dataSize:
          type: integer
          description: Optional value for the size of the partition data in bytes. The response only includes the data size if you specify `dataSize` in the `additionalFields` query parameter, and if `dataSize` was specified in the partition metadata when it was published.
          format: int64
        crc:
          type: string
          description: Optional value for the CRC of the partition data in bytes. The response only includes the data size if you specify `crc` in the `additionalFields` query parameter, and if `crc` was specified in the partition metadata when it was published.
          example: c3f276d7
        partition:
          type: string
          pattern: \d+
          description: The id of the tile
          example: '73982'
        version:
          type: integer
          description: Version of the catalog when this partition was first published
          format: int64
    Index:
      required:
      - parentQuads
      - subQuads
      type: object
      properties:
        parentQuads:
          type: array
          description: Result of the index resource call. For each parent tile, one element with the respective parent-quad data is contained in the array.
          items:
            $ref: '#/components/schemas/ParentQuad'
        subQuads:
          type: array
          description: Result of the index resource call. For each tile that contains data in the requested quadKey, one element with the respective sub-quad data is contained in the array.
          items:
            $ref: '#/components/schemas/SubQuad'
    Partition:
      required:
      - partition
      - version
      type: object
      properties:
        checksum:
          type: string
          description: The checksum of the partition. It's only provided to API calls that explicitly request a checksum and only matches partitions that have a checksum defined. You can request partitions with a specific checksum by using the `additionalFields` query parameter. The algorithm used to calculate the checksum is user-specific. Algorithms that you can use are, for example, MD5 or SHA1. The algorithm is defined in the layer configuration. And if it is not defined in the catalog configuration, consumers cannot make any assumptions on the algorithm that was used to calculate the checksum. You need to use the checksum of the data content if you want data comparison working for this catalog. The maximum length of the checksum field is 128 characters. In the case of the compressed data, the checksum is calculated for the uncompressed data.
          example: 291f66029c232400e3403cd6e9cfd36e
        compressedDataSize:
          type: integer
          description: Indicates the compressed size of the partition data in bytes when data compression is enabled. It's only provided to API calls that explicitly request the compressed data size and only matches partitions that have a compressed data size defined. You can request partitions with a specific compressed data size by using the `additionalFields` query parameter.
          format: int64
          example: 1024
        dataHandle:
          type: string
          description: You use the data handle when retrieving the data that relates to this partition. The data handle identifies a specific blob so that you can request the blob's contents with the Blob API. When requesting data from the Blob API, you must specify the catalog ID, layer ID and the dataHandle.
          example: 1b2ca68f-d4a0-4379-8120-cd025640510c
        dataSize:
          type: integer
          description: Indicates the uncompressed size of the partition data in bytes. It's only provided to API calls that explicitly request the data size and only matches partitions that have a data size defined. You can request partitions with a specific data size by using the `additionalFields` query parameter.
          format: int64
          example: 1024
        crc:
          type: string
          description: Optional value for the CRC of the partition data in bytes. The response only includes the data size if you specify `crc` in the `additionalFields` query parameter, and if `crc` was specified in the partition metadata when it was published.
          example: c3f276d7
        partition:
          type: string
          pattern: '[a-zA-Z0-9_\-\.]'
          description: The partition key. This is a unique key for a partition within a layer. If the layer's partitioning scheme is set to `heretile`, the partition key is equivalent to the tile key. The partition key cannot be empty. The maximum length of the partition key is 500 characters.
          example: '314010583'
        version:
          type: integer
          description: For active versioned partitions, the version of the catalog when this partition was last changed. For volatile partitions this will always be -1.
          format: int64
          example: 2
      description: Describes the partition object which is unique within a layer.
  parameters:
    Context:
      name: context
      in: query
      description: 'The context where the operation will be performed on a composite layers. Only available for versioned layers.


        Available context are:

        |Context|Description|

        |-------|-----------|

        |default|The default value if none is given. For composite layers the operation is executed for both layers current and the layer it extends. For normal layers this is the only valid context.|

        |extension|The operation will be executed only in the extension and no operation will be performed in the extended layer.|

        |super| The operation will be executed only in the layer being extended (super layer).|

        '
      schema:
        type: string
        enum:
        - default
        - extension
        - super
        default: default
  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://www.here.com/docs/bundle/identity-and-access-management-developer-guide/page/README.html).

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