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 likeApi.get()
,Api.put()
etc. provided for convenience.All these methods like
Api.get()
,Api.put()
etc. will raiseApiError
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
- 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
isTrue
.limit (Optional[int]) – The max. number of projects to return. Works only when
paginate
isTrue
.
- 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
- 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, likeHubApi.get_spaces()
starting with HTTP method names and an underscore, followed by a name resembling the respective API endpoint, in this caseGET /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 indefault_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
andviz
.viz_sampling (Optional[str]) – A string to indicate the sampling strength in case of
mode=viz
. Allowed values are:low
,med
,high
, andoff
, default:med
.
- Returns
A dict representing a feature collection.
- Return type
dict
Available tile types are:
quadkeys, Virtual Earth Tile System,
web, Tiled Web Map.
tms, OSGEO Tile Map Service,
here, ?
- get_space_search(space_id, tags=None, limit=None, params=None, selection=None, skip_cache=None, force_2d=None)[source]¶
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 withref_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
andlon
orref_space_id
andref_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