here.platform.api.data_metadata_api module#

This module contains a DataMetadataApi class to perform API operations.

The HERE API reference documentation used in this module can be found here: Metadata API Reference # noqa E501

class here.platform.api.data_metadata_api.DataMetadataApi(base_url: str, auth: Auth | None, platform_config: PlatformConfig, application_config: ApplicationConfig, proxies: dict | None = None)[source]#

Bases: BaseApi

This class provides access to HERE platform Metadata APIs.

The metadata service provides a way to get information (metadata) about layers and partitions stored in a catalog. This service exposes the metadata for all the partitions or all the changed partitions. For a catalog with versioned layers, you can retrieve metadata for a particular version or version range of the catalog.

compatible_versions(catalog_dependencies: dict, limit: int | None = 1, next: str | None = None) → dict[source]#

Given a list of HRNs and versions provided by the user, returns a list of versions of this catalog for which the listed HRN are either present in the direct or indirect dependencies with the same version, or are not present. Please note that versions that don’t depend on any of the provided catalog HRNs, are also considered compatible. The compatible versions are returned in reverse order, from the newest to the oldest. When there is no compatible version the service returns an empty list. When the catalog has no version a 404 is returned.

Parameters:

  • catalog_dependencies – The catalog dependencies we want to search for

  • limit – The numbers of items to return per page

  • next – The next url where the iteration will continue.

Returns:

response from the API.

Raises:

PlatformException – If platform responds with an HTTP error.

get_changes(layer_id: str, start_version: int | None = None, end_version: int | None = None, since_time: int | None = None, part: str | None = None, additional_fields: list | None = ['dataSize', 'checksum', 'compressedDataSize', 'crc'], range_header: str | None = None, billing_tag: str | None = None) → dict[source]#

Get the latest partition metadata in a version range for a versioned layer or a time range for a volatile layer. For versioned layers the range is expressed as a start and end version and might not return all changes for the partitions which were added and removed in between the specified start and end versions.

Parameters:

  • layer_id – Unique layer id. Content of this parameter refers to a valid layer ID.

  • start_version – Available/Required for versioned layers only; the beginning of the range of versions you want to get (exclusive). By convention -1 indicates the initial version before the first publication. After the first publication,the catalog version is 0

  • end_version – Available/Required for versioned layers only; the end of the range of versions you want to get (inclusive). This must be a valid catalog version greater than the startVersion.

  • since_time – Available/Required for volatile layers only; will return partitions whose data has been modified since this time, in milliseconds since epoch, inclusive.

  • part – Available/Required for versioned layers only; indicates which part of the layer shall be queried.

  • additional_fields – Available values : dataSize, checksum, compressedDataSize, crc

  • range_header – an optional Range parameter to resume download of a large response for versioned layers when there is a connection issue between the client and server. Specify a single byte range offset like this: Range: bytes=10-. This parameter is compliant with RFC 7233, but note that this parameter only supports a single byte range. The range parameter can also be specified as a query parameter, i.e. range=bytes=10-. For volatile layers use the pagination links returned in the response body.

  • billing_tag – Billing Tag is an optional free-form tag which is used for grouping billing records together.

Returns:

response from the API.

Raises:

PlatformException – If platform responds with an HTTP error.

get_changes_parts(layer_id: str, num_requested_parts: str) → dict[source]#

Return a list of Part Ids which represent the parts that can be used to limit the scope of queries of changes for the version range. 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.

Parameters:

  • layer_id – Unique layer id. Content of this parameter refers to a valid layer ID.

  • num_requested_parts – Indicates requested number of parts.

Returns:

response from the API.

Raises:

PlatformException – If platform responds with an HTTP error.

get_latest_version(start_version=-1, billing_tag: str | None = None) → int | None[source]#

Return information about the latest version for the given catalog. If the catalog doesn’t contain any versions None will be returned.

Parameters:

  • start_version –

    The catalog version returned from a prior request to /versions/latest. You should save the version from each request so that you can use it

    in the startVersion parameter of subsequent requests. If you don’t have the version from a prior request, set the parameter to -1.

  • billing_tag – Billing Tag is an optional free-form tag which is used for grouping billing records together.

Returns:

latest version number of the catalog if version exist else None

Raises:

PlatformException – If platform responds with an HTTP error.

get_layers_version(version: int, billing_tag: str | None = None) → dict[source]#

Return information about layer versions for the catalog version.

Parameters:

  • version – Catalog version.

  • billing_tag – Billing Tag is an optional free-form tag which is used for grouping billing records together.

Returns:

response from the API.

Raises:

PlatformException – If platform responds with an HTTP error.

get_minimum_version(billing_tag: str | None = None) → int | None[source]#

Return minimum version for the given catalog. If the catalog doesn’t contain any versions None will be returned.

Parameters:

billing_tag – Billing Tag is an optional free-form tag which is used for grouping billing records together.

Returns:

an int representing minimum version, if any

Raises:

PlatformException – If platform responds with an HTTP error.

get_partitions(layer_id: str, version: int | None = None, part: str | None = None, additional_fields: list | None = ['dataSize', 'checksum', 'compressedDataSize', 'crc'], range_header: str | None = None, billing_tag: str | None = None) → dict[source]#

Get the metadata for all partitions in a specific layer.

Parameters:

  • layer_id – Unique layer id. Content of this parameter refers to a valid layer ID.

  • version – If you are getting metadata from a versioned layer, specify the version of the layer you want. This parameter is required for versioned layers. If you are getting metadata from another layer type, do not specify this parameter.

  • part – Available/Required for versioned layers only; indicates which part of the layer shall be queried.

  • additional_fields – Available values : dataSize, checksum, compressedDataSize, crc

  • range_header – an optional Range parameter to resume download of a large response for versioned layers when there is a connection issue between the client and server. Specify a single byte range offset like this: Range: bytes=10-. This parameter is compliant with RFC 7233, but note that this parameter only supports a single byte range. The range parameter can also be specified as a query parameter, i.e. range=bytes=10-. For volatile layers use the pagination links returned in the response body.

  • billing_tag – Billing Tag is an optional free-form tag which is used for grouping billing records together.

Returns:

response from the API.

Raises:

PlatformException – If platform responds with an HTTP error.

get_partitions_parts(layer_id: str, num_requested_parts: str) → dict[source]#

Return a list of Part Ids which represent the parts that can be used to limit the scope of queries of the metadata for all partitions in a specific layer. 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.

Parameters:

  • layer_id – Unique layer id. Content of this parameter refers to a valid layer ID.

  • num_requested_parts – Indicates requested number of parts.

Returns:

response from the API.

Raises:

PlatformException – If platform responds with an HTTP error.

list_versions(start_version: int, end_version: int, billing_tag: str | None = None) → dict[source]#

Return information about specific catalog version(s). If the catalog doesn’t contain any versions, an empty dictionary is returned. Maximum number of versions to be returned per call is 1000 versions. If requested range is bigger than 1000 versions, 400 Bad Request will be returned.

Parameters:

  • start_version – The version number after which list of returned versions will begin. Minimum value -1 will return list starting with version 0.

  • end_version – The end of the range of versions you want to get (inclusive). This must be a valid catalog version greater than the startVersion. The maximum value for this parameter is returned from the /versions/latest endpoint. If this version does not exist, 400 Bad Request is returned

  • billing_tag – Billing Tag is an optional free-form tag which is used for grouping billing records together.

Returns:

response from the API.

Raises:

PlatformException – If platform responds with an HTTP error.

set_minimum_version(version_obj: dict, billing_tag: str | None = None)[source]#

Sets minimum version for the given catalog.

Parameters:

  • version_obj – A version object that contains new minimum version.

  • billing_tag – Billing Tag is an optional free-form tag which is used for grouping billing records together.

Raises:

PlatformException – If platform responds with an HTTP error.