{"openapi":"3.0.1","info":{"title":"Query API v1","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"}},"externalDocs":{"description":"The developer guide and related API references are available here.","url":"https://www.here.com/docs/category/data-api"},"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":{"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"}}}},"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"}}},"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."},"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}}}},"parameters":{"Context":{"name":"context","in":"query","description":"The context where the operation will be performed on a composite layers. Only available for versioned layers.\n\nAvailable context are:\n|Context|Description|\n|-------|-----------|\n|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.|\n|extension|The operation will be executed only in the extension and no operation will be performed in the extended layer.|\n|super| The operation will be executed only in the layer being extended (super layer).|\n","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.\n\nFor 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).\n"}}}}