HERE Index API

openapi: 3.2.0
info:
  title: v1 Index API
  description: Use the `index` service to get the data handles of the partitions that match a query. Then, use the data handles with the `blob` service to get the data from the partitions. For more information, see Get Data from an Index Layer. You can also use the `index` service to publish data to an index layer. For more information, see Publish to an Index Layer.
  version: 1.1.2
  x-olp-service:
    name: index
    version: v1
servers:
- url: https://use.apilookup.for.a.base.url/
security:
- Bearer: []
tags:
- name: Index
  description: Manages index layer (create, update and query indices)
paths:
  /layers/{layerID}:
    parameters:
    - $ref: '#/components/parameters/billingTag'
    get:
      tags:
      - Index
      summary: Gets the partitions that match the query
      description: Queries the index layer for the partitions that match the query. Returns each partition that matches the query, including each partition's data handle, which you use with the `blob` API to retrieve data for each partition.
      operationId: Index API v1 performQuery
      parameters:
      - name: layerID
        in: path
        description: The ID of the index layer you want to query.
        required: true
        schema:
          type: string
        x-example: index
      - name: query
        in: query
        description: An RSQL query to use to retrieve partitions that match the query. For more information, see [Get Index Data from an Index Layer](https://www.here.com/docs/bundle/data-api-developer-guide/page/rest/getting-data-index.html). The query must use the indexing attributes defined in the index layer.
        required: true
        schema:
          type: string
        x-example: tile==377782527;hour>=0;hour<2
      - name: part
        in: query
        description: Indicates which part of the layer shall be queried.
        required: false
        schema:
          type: string
        x-example: 7a320ce9e4d04d749c7a19810f99a3a1
      responses:
        '200':
          description: OK - Query executed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataResponse'
        '400':
          description: Bad Request - The request is invalid. Verify and retry.
        '401':
          description: Unauthorized - The credentials provided do not authorize the user to perform this operation.
        '403':
          description: Forbidden - The user is not authorized to perform the query on the resource specified.
        '404':
          description: Not Found - The criteria set in the query is not valid.
      x-olp-access-type: resource
      deprecated: false
    put:
      tags:
      - Index
      summary: Updates index layer partitions
      description: Modifies partitions in an index layer.
      operationId: Index API v1 performUpdate
      parameters:
      - name: layerID
        in: path
        description: The layer ID of the index layer.
        required: true
        schema:
          type: string
        x-example: index
      requestBody:
        description: Contains the data you want to add or remove from the index layer
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateIndexRequest'
      responses:
        '200':
          description: OK - The index was successfully updated.
        '401':
          description: Unauthorized - The credentials provided do not authorize the user to perform this operation.
        '403':
          description: Forbidden - The user is not authorized to update the catalog and layer provided.
        '404':
          description: Not Found - A layer with the given name does not exist.
        '409':
          description: Conflict - An index with the given ID already exists
      x-olp-access-type: resource
      deprecated: false
    post:
      tags:
      - Index
      summary: Inserts index data to an index layer
      description: Adds index data for a given data blob to an index layer. For more information, see Publish to an Index Layer.
      operationId: Index API v1 insertIndexes
      parameters:
      - name: layerID
        in: path
        description: The layer ID of the index layer.
        required: true
        schema:
          type: string
        x-example: index
      requestBody:
        description: An array of index attributes and values to be inserted.
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/Index'
        required: true
      responses:
        '201':
          description: OK - The index was successfully created.
        '400':
          description: Bad Request - The request is invalid. Verify and retry.
        '401':
          description: Unauthorized - The credentials can't be authenticated by the system.
        '403':
          description: Forbidden - The user is not authorized to create indexes.
        '404':
          description: 'Not Found - A layer with the given name does not exist. '
        '409':
          description: Conflict - An index with the given ID already exists.
      x-olp-access-type: resource
      deprecated: false
    delete:
      tags:
      - Index
      summary: Deletes the partitions that match the query
      description: Deletes the partitions that match the query in the index layer. Returns the delete request ID, which you can use to query the status of the delete operation.
      operationId: Index API v1 performDelete
      parameters:
      - name: layerID
        in: path
        description: The ID of the index layer you want to delete from.
        required: true
        schema:
          type: string
        x-example: index
      - name: deleteQuery
        in: query
        description: An RSQL query to use to delete the partitions that match the query. For more information, see [Delete Index Data from an Index Layer](https://www.here.com/docs/bundle/data-api-developer-guide/page/rest/deleting-data-index.html). The query must use the indexing attributes defined in the index layer.
        required: true
        schema:
          type: string
        x-example: tile==377782527;hour>=0;hour<2
      responses:
        '202':
          description: Accepted - Delete request accepted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResponse'
        '400':
          description: Bad Request - The request is invalid. Verify and retry.
        '401':
          description: Unauthorized - The credentials provided do not authorize the user to perform this operation.
        '403':
          description: Forbidden - The user is not authorized to perform the query on the resource specified.
        '404':
          description: Not Found - The criteria set in the query is not valid.
      x-olp-access-type: resource
      deprecated: false
  /layers/{layerID}/deleteRequest/{deleteId}:
    parameters:
    - $ref: '#/components/parameters/billingTag'
    get:
      tags:
      - Index
      summary: Returns the status of the delete request
      description: 'Returns the details of the specified delete request. Delete request can be in one of the following states: Scheduled, Processing, Failed, Succeeded. See Data API Developer’s Guide in the Documentation section for the delete request state diagram.'
      operationId: Index API v1 getDeleteRequestStatus
      parameters:
      - name: layerID
        in: path
        description: The ID of the index layer you want to get the delete request status for.
        required: true
        schema:
          type: string
        x-example: index
      - name: deleteId
        in: path
        description: Id of the delete request returned from the index delete operation.
        required: true
        schema:
          type: string
        x-example: e07191de-8ab8-49f5-a11d-8240e1b93ab7
      responses:
        '200':
          description: Delete request status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteRequestStatus'
        '400':
          description: Bad Request - The request is invalid. Verify and retry.
        '401':
          description: Unauthorized - The credentials provided do not authorize the user to perform this operation.
        '403':
          description: Forbidden - The user is not authorized to perform the operation on the resource specified.
        '404':
          description: Not Found - The criteria set in the request are not valid.
      x-olp-access-type: resource
      deprecated: false
  /layers/{layerID}/parts:
    parameters:
    - $ref: '#/components/parameters/billingTag'
    get:
      tags:
      - Index
      summary: Get partIds for parallel queries
      description: Returns a list of Part Ids which represent the layer parts that can be used to limit the scope of a query operation. This allows to run parallel queries with multiple parts. The user has to provide the desired number of parts and the service will return a list of Part Ids. Please note in some cases the requested number of parts will make them too small and in this case the service might return lesser amount of the parts than requested.
      operationId: Index API v1 getParts
      parameters:
      - name: layerID
        in: path
        description: The ID of the index layer you want to query.
        required: true
        schema:
          type: string
        x-example: index
      - name: numRequestedParts
        in: query
        description: Indicates requested number of layer parts.
        required: true
        schema:
          type: integer
        allowEmptyValue: false
        x-example: 12
      responses:
        '200':
          description: OK - Operation executed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartsResponse'
        '400':
          description: Bad Request - The request is invalid. Verify number of requested parts and retry.
        '401':
          description: Unauthorized - The credentials provided do not authorize the user to perform this operation.
        '403':
          description: Forbidden - The user is not authorized to perform the query on the resource specified.
        '404':
          description: Not Found - A layer with the given name does not exist.
      x-olp-access-type: resource
      deprecated: false
components:
  schemas:
    DeleteRequestStatus:
      type: object
      properties:
        deleteId:
          type: string
          format: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
          example: e07191de-8ab8-49f5-a11d-8240e1b93ab7
        state:
          type: string
          enum:
          - Scheduled
          - Processing
          - Failed
          - Succeeded
          description: 'The state of the delete request.

            - `Scheduled` - The delete request was successfully scheduled.

            - `Processing` - The delete request is being executed.

            - `Failed` - The delete request failed. Please try again.

            - `Succeeded` - The delete request finished successfully. The number of deleted records is provided in the `count` field.

            '
          readOnly: true
          example: Failed
        message:
          type: string
          description: A message describing the state.
          readOnly: true
          example: Delete request failed due to ....
        count:
          type: integer
          description: Number of deleted index records.
          readOnly: true
          example: 0
      title: DeleteRequestStatus
    DataResponse:
      type: object
      properties:
        data:
          type: array
          example:
          - id: 7a320ce9-e4d0-4d74-9c7a-19810f99a3a1
            size: 100
            checksum: checksum
            metadata: '{"ingestionTime": "1532018660873"}'
            timestamp: 1543351987660
            crc: crc
            hour: 0
            tile: 377782527
            containsProbe: true
            eventType: vss
          items:
            $ref: '#/components/schemas/MapStringObject'
      title: DataResponse
    MapStringObject:
      type: object
      title: MapStringObject
      additionalProperties:
        type: object
    DeleteResponse:
      type: object
      properties:
        deleteId:
          type: string
          format: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
          example: e07191de-8ab8-49f5-a11d-8240e1b93ab7
      title: DeleteResponse
    PartId:
      type: object
      properties:
        partId:
          type: string
          example: e07191de8ab849f5a11d8240e1b93ab7
      title: PartId
    PartsResponse:
      type: object
      properties:
        parts:
          type: array
          example:
          - partId: 7a320ce9e4d04d749c7a19810f99a3a1
          items:
            $ref: '#/components/schemas/PartId'
      title: PartsResponse
    Index:
      type: object
      properties:
        checksum:
          type: string
          format: byte
          example: checksum
          description: The checksum of the data being indexed by this index record.
        crc:
          type: string
          format: byte
          example: crc
          description: The cyclic redundancy check (CRC) of the data being indexed by this index record.
        fields:
          type: object
          additionalProperties:
            type: object
          example:
            hour: 0
            tile: 377782527
            containsProbe: true
            eventType: vss
          description: The indexing attributes for the data being indexed by this index record. The attributes must match the indexing attributes defined for the index layer. To get or set the index attributes for an index layer, use the `config` API.
        id:
          type: string
          format: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
          example: 7a320ce9-e4d0-4d74-9c7a-19810f99a3a1
          description: The unique identifier (UUID) of the data being indexed by this index record.
        metadata:
          type: object
          example:
            ingestionTime: '1532018660873'
          description: User-defined fields that can store extra metadata about this index record.
          additionalProperties:
            type: string
        size:
          type: integer
          format: int64
          example: 100
          description: The size of the data being indexed by this index record.
      title: Index
    UpdateIndexRequest:
      type: object
      properties:
        additions:
          type: array
          items:
            $ref: '#/components/schemas/Index'
        deleteBlob:
          type: boolean
          default: false
          description: Indicates if the blobs listed in the removals section shall be deleted. Please note the blobs deletion is not instant but deferred in time.
        removals:
          type: array
          example:
          - e07191de-8ab8-49f5-a11d-8240e1b93ab7
          - 99e0bde0-935c-4382-b940-fe0d2cf2ec23
          items:
            type: string
            format: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
      title: UpdateIndexRequest
  parameters:
    billingTag:
      in: query
      name: billingTag
      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
  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