xyzspaces.apis module

This module does access the APIs of an XYZ Hub server or HERE Data Hub.

It provides classes like HubApi, ProjectApi, and TokenApi to interact with the respective XYZ APIs in a programmatic way.

class xyzspaces.apis.Api(config=None)[source]

Bases: object

A low-level HTTP RESTful API client.

This uses requests to make HTTP requests with typical parameters and will return the entire response when calling instances directly, or when using the aliased HTTP methods like Api.get(), Api.put() etc. provided for convenience.

All these methods like Api.get(), Api.put() etc. will raise ApiError if the status code of the HTTP response is not in the interval [200, 300).

This class is a base class for concrete HERE XYZ APIs, but can also be used outside of that particular context for any RESTful API, maybe with slight changes regarding authentication.

Parameters

config (Optional[xyzspaces.config.default.XYZConfig]) –

__init__(config=None)[source]

Instantiate an Api object.

Parameters

config (Optional[xyzspaces.config.default.XYZConfig]) –

__call__(method, path='', params=None, headers=None, cookies=None, json=None, data=None, proxies=None)[source]

Make an API call with parameters passed to requests.

Parameters
  • method (str) – The HTTP method name, e.g. “GET”, “PUT”, etc.

  • path (Optional[str]) – The HTTP path to be appended to the server attribute.

  • params (Optional[Dict]) – A dict holding the HTTP query parameters.

  • headers (Optional[Dict]) – A dict holding the HTTP request headers.

  • cookies (Optional[Dict]) – A dict holding the HTTP request cookies.

  • json (Optional[Dict]) – A JSON object (usually a dict) to be passed as request body with content-type application/json.

  • data (Optional[Dict]) – A str to be passed as request body with content-type application/x-www-form-urlencoded.

  • proxies (Optional[Dict]) – A dict holding the HTTP proxies to be used.

Returns

The HTTP response returned by the requests package.

Raises

ApiError – If the status code of the HTTP response is not in the interval [200, 300).

Return type

requests.models.Response

get(**kwargs)[source]

Send a HTTP GET request.

Parameters

kwargs – Keyword arguments passed when sending the HTTP request.

Returns

The HTTP response.

Return type

requests.models.Response

put(**kwargs)[source]

Send a HTTP PUT request.

Parameters

kwargs – Keyword arguments passed when sending the HTTP request.

Returns

The HTTP response.

Return type

requests.models.Response

patch(**kwargs)[source]

Send a HTTP PATCH request.

Parameters

kwargs – Keyword arguments passed when sending the HTTP request.

Returns

The HTTP response.

Return type

requests.models.Response

post(**kwargs)[source]

Send a HTTP POST request.

Parameters

kwargs – Keyword arguments passed when sending the HTTP request.

Returns

The HTTP response.

Return type

requests.models.Response

delete(**kwargs)[source]

Send a HTTP DELETE request.

Parameters

kwargs – Keyword arguments passed when sending the HTTP request.

Returns

The HTTP response.

Return type

requests.models.Response

class xyzspaces.apis.ProjectApi(config=None)[source]

Bases: xyzspaces.apis.Api

XYZ RESTful Project API abstraction.

Instances of this class allow to manage XYZ Hub projects.

API calls must be authenticated via a bearer token which needs to be provided in env variable called as XYZ_TOKEN or in config object when initialising an instance.

Parameters

config (Optional[xyzspaces.config.default.XYZConfig]) –

__init__(config=None)[source]

Instantiate a ProjectApi object.

Parameters

config (Optional[xyzspaces.config.default.XYZConfig]) –

get_projects(paginate=None, handle=None, limit=None)[source]

List the projects either for the token owner or list the published projects.

Parameters
  • paginate (Optional[bool]) – A Boolean telling if the results should be paginated (default: ?).

  • handle (Optional[int]) – A string to be used when running the next request in a sequence of pagninated responses. Works only when paginate is True.

  • limit (Optional[int]) – The max. number of projects to return. Works only when paginate is True.

Returns

A JSON object containing information about the projects.

Return type

dict

get_project(project_id)[source]

Get the project by ID.

Parameters

project_id (str) – A string representing the project ID.

Returns

A JSON object with information about the requested project.

Return type

dict

post_project(data)[source]

Create a project.

Parameters

data – A JSON object describing the project to be created.

Returns

A JSON object with all information about the created project.

Return type

dict

put_project(project_id, data)[source]

Update a project by ID.

Update the project with the provided project ID and create it if it does not exist. This will replace the whole project definition.

Parameters
  • project_id (str) – A string representing the desired project ID.

  • data – A JSON object describing the project details to be updated.

Returns

A JSON object with information about the updated project.

Return type

dict

patch_project(project_id, data)[source]

Update parts of a project by ID.

Parameters
  • project_id (str) – A string representing the desired project ID.

  • data – A JSON object describing the project parts to be updated.

Returns

A JSON object with information about the updated project.

Return type

dict

delete_project(project_id)[source]

Delete a project by ID.

Parameters

project_id (str) – A string representing the desired project ID.

Returns

An empty string if the operation was successful.

Return type

str

class xyzspaces.apis.TokenApi(config=None)[source]

Bases: xyzspaces.apis.Api

XYZ RESTful Token API abstraction.

Instances of this API class allow to manage HERE XYZ tokens.

API calls must be authenticated via authenticated access cookies derived from the username and password of an existing HERE developer account with access to HERE XYZ. These need to be provided as a credentials parameter when initialising an instance.

Example:

>>> from xyzspaces.apis import TokenApi
>>> from xyzspaces.config.default import XYZConfig
>>> config = XYZConfig.from_default()
>>> api = TokenApi(config=config)
>>> api.get_tokens()
[...]
Parameters

config (Optional[xyzspaces.config.default.XYZConfig]) –

__init__(config=None)[source]

Instantiate a TokenApi object.

Parameters

config (Optional[xyzspaces.config.default.XYZConfig]) –

get_token(token_id, **kwargs)[source]

Get info for given token ID.

Parameters
  • token_id (str) – A string representing the requested token.

  • kwargs – A dict with additional parameters passed to the HTTP request made when provided.

Returns

A JSON object with the information about the requested token.

Return type

dict

get_tokens(**kwargs)[source]

Get list of tokens for the authenticated user.

Parameters

kwargs – A dict with additional parameters passed to the HTTP request made when provided.

Returns

A list with information about all available tokens.

Return type

list

post_token(json={}, **kwargs)[source]

Create a new permanent or temporary token.

Parameters
  • json (Dict) – A dict with information about the token to be created.

  • kwargs – A dict with additional parameters passed to the HTTP request made when provided.

Returns

A JSON object with all information about the created token.

Return type

dict

delete_token(token_id, **kwargs)[source]

Delete the token with the provided ID.

Parameters
  • token_id (str) – A string representing a valid token.

  • kwargs – A dict with additional parameters passed to the HTTP request made when provided.

Returns

An empty string if the operation was successful.

Return type

str

class xyzspaces.apis.HubApi(config=None)[source]

Bases: xyzspaces.apis.Api

XYZ RESTful Hub API abstraction.

Instances of this API class allow to manage HERE XYZ spaces.

API calls must be authenticated via a bearer token which needs to be provided as a credentials parameter when initialising an instance.

A few convenience methods for calling HTTP methods directly are inherited from the Api base class, and can also be used, although this class provides dedicated methods for the Hub API, like HubApi.get_spaces() starting with HTTP method names and an underscore, followed by a name resembling the respective API endpoint, in this case GET /hub/spaces.

Example:

>>> from xyzspaces.apis import HubApi
>>> from xyzspaces.config.default import XYZConfig
>>> config = XYZConfig.from_default()
>>> api = HubApi(config=config)
>>> api.get_spaces()
[...]

This is based on the HERE XYZ Hub API specification defined here: https://xyz.api.here.com/hub/static/swagger/#/

Parameters

config (Optional[xyzspaces.config.default.XYZConfig]) –

__init__(config=None)[source]

Instantiate an HubApi object.

Parameters

config (Optional[xyzspaces.config.default.XYZConfig]) – An object of class:XYZConfig, If not provied XYZ_TOKEN will be used from environment variable and other configurations will be used as defined in default_config

get_hub(params=None)[source]

Get basic information about the XYZ Hub.

Parameters

params (Optional[dict]) – A dict holding the HTTP query parameters.

Returns

A JSON object with hub information.

Return type

dict

get_spaces(params=None)[source]

Get Spaces information.

Parameters

params (Optional[dict]) – A dict holding the HTTP query parameters.

Returns

A JSON object with list of spaces.

Return type

dict

get_space(space_id, params=None)[source]

Get a space by ID.

Parameters
  • space_id (str) – The desired space ID.

  • params (Optional[dict]) – A dict for query params.

Returns

A JSON object with information about the space_id.

Return type

dict

post_space(data)[source]

Create a space.

Parameters

data (dict) – A dict describing the space to be created.

Returns

A JSON object with all information about the created space.

Return type

dict

patch_space(space_id, data)[source]

Update a space.

Parameters
  • space_id (str) – A string representing the desired space ID.

  • data (dict) – A JSON object describing the space attributes to be updated.

Returns

A JSON object with information about the updated space.

Return type

dict

delete_space(space_id)[source]

Delete a space.

Parameters

space_id (str) – A string representing desired space ID.

Returns

An empty string if the operation was successful.

Return type

str

get_space_features(space_id, feature_ids, force_2d=None)[source]

Get features by ID.

Parameters
  • space_id (str) – The desired space ID.

  • feature_ids (List[str]) – A list of feature_ids.

  • force_2d (Optional[bool]) – If set to True the features in the response will have only X and Y components, by default all x,y,z coordinates will be returned.

Returns

A feature collection with all features inside the specified space.

Return type

dict

Example: Get single feature from space

>>> feats = api.get_space_features(
...         space_id=space_id, feature_ids=["GER", "BRA"])
>>> print(feats)
get_space_feature(space_id, feature_id, force_2d=None)[source]

Get a feature by ID.

Parameters
  • space_id (str) – The desired space ID.

  • feature_id (str) – The desired feature ID.

  • force_2d (Optional[bool]) – If set to True the features in the response will have only X and Y components, by default all x,y,z coordinates will be returned.

Returns

A feature with the specified feature ID inside the space with the specified ID.

Return type

dict

Example: Read the feature from the space.

>>>     feature = api.get_space_feature(
...     space_id=space_id, feature_id=feature_id)
>>>     print(json.dumps(feature, indent=4, sort_keys=True))
get_space_statistics(space_id)[source]

Get statistics.

Parameters

space_id (str) – The desired space ID.

Returns

A JSON object with some statistics about the specified space.

Return type

dict

Example:

>>>     stats = api.get_space_statistics(space_id=space_id)
>>>     print(json.dumps(stats, indent=4, sort_keys=True))
get_space_bbox(space_id, bbox, tags=None, clip=None, limit=None, params=None, selection=None, skip_cache=None, clustering=None, clusteringParams=None, force_2d=None)[source]

Get features inside some given bounding box.

Parameters
  • space_id (str) – A string with the ID of the desired XYZ space.

  • bbox (List[Union[float, int]]) – A list of four numbers representing the West, South, East and North margins, respectively, of the bounding box.

  • tags (Optional[List[str]]) – A list of strings holding tag values.

  • clip (Optional[bool]) – A Boolean indicating if the result should be clipped (default: False).

  • limit (Optional[int]) – A max. number of features to return in the result.

  • params (Optional[dict]) –

  • selection (Optional[List[str]]) –

  • skip_cache (Optional[bool]) –

  • clustering (Optional[str]) –

  • clusteringParams (Optional[dict]) –

  • force_2d (Optional[bool]) – If set to True the features in the response will have only X and Y components, by default all x,y,z coordinates will be returned.

Returns

A dict representing a feature collection.

Return type

dict

Example:

>>>     bb = [0, 0, 20, 20]
>>>     bbox = api.get_space_bbox(space_id=space_id, bbox=bb)
>>>     print(len(bbox["features"]))
>>>     print(bbox["type"])
get_space_tile(space_id, tile_type, tile_id, tags=None, clip=None, params=None, selection=None, skip_cache=None, clustering=None, clusteringParams=None, margin=None, limit=None, force_2d=None, mode=None, viz_sampling=None)[source]

Get features in tile.

Parameters
  • space_id (str) – A string with the ID of the desired XYZ space.

  • tile_type (str) – A string with the name of a tile type, one of “quadkeys”, “web”, “tms” or “here”. See below.

  • tile_id (str) – A string holding a valid tile ID according to the specified tile_type.

  • tags (Optional[List[str]]) – A list of strings holding tag values.

  • clip (Optional[bool]) – A Boolean indicating if the result should be clipped (default: False).

  • margin (Optional[int]) –

  • limit (Optional[int]) – A max. number of features to return in the result.

  • params (Optional[dict]) –

  • selection (Optional[List[str]]) –

  • skip_cache (Optional[bool]) –

  • clustering (Optional[str]) –

  • clusteringParams (Optional[dict]) –

  • force_2d (Optional[bool]) – If set to True the features in the response will have only X and Y components, by default all x,y,z coordinates will be returned.

  • mode (Optional[str]) – A string to indicate how to optimize the resultset and geometries for display. Allowed values are raw and viz.

  • viz_sampling (Optional[str]) – A string to indicate the sampling strength in case of mode=viz. Allowed values are: low, med, high, and off, default: med.

Returns

A dict representing a feature collection.

Return type

dict

Available tile types are:

Search for features.

Parameters
  • space_id (str) – A string with the ID of the desired XYZ space.

  • tags (Optional[List[str]]) – A list of strings holding tag values.

  • limit (Optional[int]) – A max. number of features to return in the result.

  • params (Optional[dict]) –

  • selection (Optional[List[str]]) –

  • skip_cache (Optional[bool]) –

  • force_2d (Optional[bool]) – If set to True the features in the response will have only X and Y components, by default all x,y,z coordinates will be returned.

Returns

A dict representing a feature collection.

Return type

dict

Example:

>>>     feats = api.get_space_search(space_id=space_id)
>>>     print(feats["type"] )
>>>     print(len(feats["features"]) )
get_space_iterate(space_id, limit, force_2d=None)[source]

Iterate features in the space (yielding them one by one).

Parameters
  • space_id (str) – A string representing desired space ID.

  • limit (int) – A max. number of features to return in the result.

  • force_2d (Optional[bool]) – If set to True the features in the response will have only X and Y components, by default all x,y,z coordinates will be returned.

Yields

A feature in space.

Return type

Generator

get_space_all(space_id, limit, max_len=1000)[source]

Get all features as one single GeoJSON feature collection.

This is a convenience method, not directly available in the XYZ API. It hides the API paging mechanism and returns all data in one chunk. So be careful if you don’t know how much data you will get.

Parameters
  • space_id (str) – A string representing desired space ID.

  • limit (int) – A max. number of features to return in the result.

  • max_len – A max. number of features to return in the result.

Returns

A dict representing a feature collection.

Return type

dict

Example:

>>>     fc = api.get_space_all(space_id=space_id, limit=100)
>>>     print(len(fc["features"]) )
>>>     print(fc["type"])
get_space_count(space_id)[source]

Get feature count.

Parameters

space_id (str) – A string with the ID of the desired XYZ space.

Returns

A dict containing the number of features inside the specified space.

Return type

dict

put_space_features(space_id, data, add_tags=None, remove_tags=None)[source]

Create or replace multiple features.

Parameters
  • space_id (str) – A string with the ID of the desired XYZ space.

  • data (dict) – A JSON object describing one or more features to add.

  • add_tags (Optional[List[str]]) – A list of strings describing tags to be added to the features.

  • remove_tags (Optional[List[str]]) – A list of strings describing tags to be removed from the features.

Returns

A dict representing a feature collection.

Return type

dict

Example:

>>> from xyzspaces.datasets import get_countries_data
>>>     gj_countries = get_countries_data()
>>>     features = api.put_space_features(
...     space_id=space_id,
...     data=gj_countries,
...     add_tags=["foo", "bar"],
...     remove_tags=["bar"],
... )
>>> print(features)
post_space_features(space_id, data, add_tags=None, remove_tags=None)[source]

Modify multiple features in the space.

Parameters
  • space_id (str) – A string with the ID of the desired XYZ space.

  • data (dict) – A JSON object describing one or more features to modify.

  • add_tags (Optional[List[str]]) – A list of strings describing tags to be added to the features.

  • remove_tags (Optional[List[str]]) – A list of strings describing tags to be removed from the features.

Returns

A dict representing a feature collection.

Return type

dict

Example:

>>> data = dict(type="FeatureCollection", features=[deu, ita])
>>> space_features = api.post_space_features(
...     space_id=space_id, data=data)
>>> print(space_features)
delete_space_features(space_id, id=None, tags=None)[source]

Delete multiple features from the space.

Parameters
  • space_id (str) – A string with the ID of the desired XYZ space.

  • id (Optional[List[str]]) – A list of feature IDs to delete.

  • tags (Optional[List[str]]) – A list of strings describing tags the features to be deleted must have.

Returns

A response from API call.

Return type

str

Example:

>>>     deu = api.get_space_feature(space_id=space_id, feature_id="DEU")
>>>     ita = api.get_space_feature(space_id=space_id, feature_id="ITA")
>>>     deleted_features = api.delete_space_features(
...     space_id=space_id, id=["DEU", "ITA"])  # noqa: E501
put_space_feature(space_id, data, feature_id=None, add_tags=None, remove_tags=None)[source]

Create or replace a single feature.

Parameters
  • space_id (str) – A string with the ID of the desired XYZ space.

  • data (dict) – A JSON object describing the feature to be added.

  • feature_id (Optional[str]) – A string with the ID of the feature to be created.

  • add_tags (Optional[List[str]]) – A list of strings describing tags to be added to the feature.

  • remove_tags (Optional[List[str]]) – A list of strings describing tags to be removed from the feature.

Returns

A dict representing a feature.

Return type

dict

Example:

>>>     api.put_space_feature(
...     space_id=space_id, feature_id=feature_id, data=fra)
patch_space_feature(space_id, feature_id, data, add_tags=None, remove_tags=None)[source]

Patch a single feature in the space.

Parameters
  • space_id (str) – A string with the ID of the desired XYZ space.

  • feature_id (str) – A string with the ID of the feature to be modified.

  • data (dict) – A JSON object describing the feature to be changed.

  • add_tags (Optional[List[str]]) – A list of strings describing tags to be added to the feature.

  • remove_tags (Optional[List[str]]) – A list of strings describing tags to be removed from the feature.

Returns

A dict representing a feature.

Return type

dict

delete_space_feature(space_id, feature_id)[source]

Delete a single feature from the space.

Parameters
  • space_id (str) – A string with the ID of the desired XYZ space.

  • feature_id (str) – A string with the ID of the feature to be deleted.

Returns

An empty string if the operation was successful.

Return type

str

get_space_spatial(space_id, lat=None, lon=None, ref_space_id=None, ref_feature_id=None, radius=None, tags=None, limit=None, params=None, selection=None, skip_cache=None, force_2d=None)[source]

Get features with radius search.

Parameters
  • space_id (str) – A string with the ID of the desired XYZ space.

  • lat (Optional[float]) – A float in WGS’84 decimal degree (-90 to +90) of the center Point.

  • lon (Optional[float]) – A float in WGS’84 decimal degree (-180 to +180) of the center Point.

  • ref_space_id (Optional[str]) – A string as alternative for defining center coordinates, it is possible to reference a geometry in a space, hence it is needed to provide the ref_space_id where the referenced feature is stored. Always to use in combination with ref_feature_id.

  • ref_feature_id (Optional[str]) – A string as unique identifier of a feature in the referenced space. The geometry of that feature gets used for the spatial query. Always to use in combination with ref_space_id.

  • radius (Optional[int]) – An int in meter which defines the diameter of the search request.

  • tags (Optional[List[str]]) – A list of strings holding tag values.

  • limit (Optional[int]) – A max. number of features to return in the result.

  • params (Optional[dict]) – A dict holding the HTTP query parameters.

  • selection (Optional[List[str]]) – A list of strings holding properties values.

  • skip_cache (Optional[bool]) – A Boolean if set to True the response is not returned from cache.

  • force_2d (Optional[bool]) – If set to True the features in the response will have only X and Y components, by default all x,y,z coordinates will be returned.

Returns

A dict representing a feature collection.

Raises

ValueError – If incorrect params are passed, either lat and lon or ref_space_id and ref_feature_id must have a value.

Return type

dict

post_space_spatial(space_id, data, radius=None, tags=None, limit=None, params=None, selection=None, skip_cache=None, force_2d=None)[source]

Post features which intersect the provided geometry.

Parameters
  • space_id (str) – A string with the ID of the desired XYZ space.

  • data (dict) – A JSON object which is getting used for the spatial search.

  • radius (Optional[int]) – An int which defines the diameter(meters) of the search request.

  • tags (Optional[List[str]]) – A list of strings holding tag values.

  • limit (Optional[int]) – A max. number of features to return in the result.

  • params (Optional[dict]) – A dict holding the HTTP query parameters.

  • selection (Optional[List[str]]) – A list of strings holding properties values.

  • skip_cache (Optional[bool]) – A Boolean if set to True the response is not returned from cache.

  • force_2d (Optional[bool]) – If set to True the features in the response will have only X and Y components, by default all x,y,z coordinates will be returned.

Returns

A dict representing a feature collection.

Return type

dict