Class: Service

H .service .iml.Service

new H.service.iml.Service (options)

This class encapsulates the HERE Interactive Map Layer Data API in a service stub, providing methods to access its resources.

It's not allowed to call the constructor directly (an IllegalOperationError is thrown). Instead an instance of this Service can be retrieved by calling the factory method H.service.Platform#getIMLService on a platform instance.

Name	Type	Description
`options`	H.service.iml.Service.Options	Configuration options for the service.

Throws:

If instantiated directly.

Example

// Assumption: the platform is instantiated
const imlService = platform.getIMLService();
imlService.getStatistics('catalog_hrn_goes_here', 'layer_id_goes_here', console.log, console.error);

Extends

H.service.Service

Members

H.service.iml.Service.CONFIG_KEY string staticconstant

The property name to use when specifying options for this service within the H.service.Platform.Options#servicesConfig.

Methods

addEventListener (type, handler, opt_capture, opt_scope) inherited

This method adds a listener for a specific event.

Note that to prevent potential memory leaks, you must either call removeEventListener or dispose on the given object when you no longer need it.

Name	Type	Description
`type`	string	The name of the event
`handler`	function	An event handler function
`opt_capture`	boolean	optional `true` indicates that the method should listen in the capture phase (bubble otherwise)
`opt_scope`	Object	optional An object defining the scope for the handler function

addOnDisposeCallback (callback, opt_scope) inherited

This method adds a callback which is triggered when the EventTarget object is being disposed.

Name	Type	Description
`callback`	function	The callback function.
`opt_scope`	Object	optional An optional scope for the callback function

deleteFeature (featureId, catalogHrn, layerId, onResult, onError)H.util.ICancelable

To delete an individual feature from the layer. Creates a DELETE request that returns an empty response with 204 (No Content) status code in case of success.

Name	Type	Description
`featureId`	string	A feature identifier.
`catalogHrn`	string	A HERE Resource Name (HRN) for the catalog.
`layerId`	string	An identifier for the layer in the catalog.
`onResult`	function(H.service.ServiceResult)	A callback function to be called with an empty response.
`onError`	function(Error)	A callback function to be called in case of failed request.

See:

Data API Reference - Deletes a feature

Throws:

If at least one of required arguments is not supplied or has a wrong type.

Returns:

Type	Description
H.util.ICancelable	A handle that allows to cancel the request.

deleteFeatures (featureIds, catalogHrn, layerId, onResult, onError)H.util.ICancelable

To delete features from the layer.

Name	Type	Description
`featureIds`	Array.<string>	An array of feature identifiers.
`catalogHrn`	string	A HERE Resource Name (HRN) for the catalog.
`layerId`	string	An identifier for the layer in the catalog.
`onResult`	function(H.service.ServiceResult)	A callback function to be called with a FeatureCollection object.
`onError`	function(Error)	A callback function to be called in case of failed request.

See:

Throws:

If at least one of required arguments is not supplied or has a wrong type.

Returns:

Type	Description
H.util.ICancelable	A handle that allows to cancel the request.

dispatchEvent (evt) inherited

This method dispatches an event on the EventTarget object.

Name	Type	Description
`evt`	H.util.Event \| string	An object representing the event or a string with the event name

dispose () inherited

This method removes listeners from the given object. Classes that extend EventTarget may need to override this method in order to remove references to DOM Elements and additional listeners.

getFeatureById (featureId, catalogHrn, layerId, onResult, onError, opt_params)H.util.ICancelable

To retrieve an individual feature in the layer, by feature ID.

Name	Type	Description
`featureId`	string	A feature identifier.
`catalogHrn`	string	A HERE Resource Name (HRN) for the catalog.
`layerId`	string	An identifier for the layer in the catalog.
`onResult`	function(H.service.ServiceResult)	A callback function to be called with an object containing individual feature.
`onError`	function(Error)	A callback function to be called in case of failed request.
`opt_params`	H.service.ServiceParameters	optional Optional service parameters to be added to the request.

See:

Data API Guide - Get Data from an Interactive Map Layer - Get features by ID - Requesting one feature

Throws:

If at least one of required arguments is not supplied or has a wrong type.

Returns:

Type	Description
H.util.ICancelable	A handle that allows to cancel the request.

getFeaturesByBoundingBox (params, catalogHrn, layerId, onResult, onError)H.util.ICancelable

To retrieve a list of features in the layer, by bounding box.

Name	Type	Description
`params`	H.service.ServiceParameters	An object with either `bbox` or a full set of `north`+`east`+`south`+`west` values specifying a bounding box, together with other (optional) service parameters.
`catalogHrn`	string	A HERE Resource Name (HRN) for the catalog.
`layerId`	string	An identifier for the layer in the catalog.
`onResult`	function(H.service.ServiceResult)	A callback function to be called with a FeatureCollection object.
`onError`	function(Error)	A callback function to be called in case of failed request.

See:

Data API Guide - Get Data from an Interactive Map Layer - Get features by bounding box

Throws:

If at least one of required arguments is not supplied or has a wrong type.

Returns:

Type	Description
H.util.ICancelable	A handle that allows to cancel the request.

getFeaturesByGeometryAndRadius (params, geojsonObject, catalogHrn, layerId, onResult, onError)H.util.ICancelable

To retrieve a list of features in the layer, by geometry and radius. Creates a POST request with a given GeoJSON geometry as its body.

Name	Type	Description
`params`	H.service.ServiceParameters	An object with `radius` and other (optional) service parameters.
`geojsonObject`	Object	A GeoJSON Geometry object (e.g. `Point`, `Polygon`, ...) to calculate an origin point.
`catalogHrn`	string	A HERE Resource Name (HRN) for the catalog.
`layerId`	string	An identifier for the layer in the catalog.
`onResult`	function(H.service.ServiceResult)	A callback function to be called with a FeatureCollection object.
`onError`	function(Error)	A callback function to be called in case of failed request.

See:

Data API Reference - Get features which intersects the provided geometry

Throws:

If at least one of required arguments is not supplied or has a wrong type.

Returns:

Type	Description
H.util.ICancelable	A handle that allows to cancel the request.

Example

const polygon = new H.map.Polygon(...);
imlService.getFeaturesByGeometryAndRadius(
  {radius: 1000},
  polygon.toGeoJSON().geometry,
  'catalog_hrn_goes_here', 'layer_id_goes_here',
  console.log, console.error,
);

getFeaturesById (featureIds, catalogHrn, layerId, onResult, onError, opt_params)H.util.ICancelable

To retrieve a list of features in the layer, by their IDs.

Name	Type	Description
`featureIds`	Array.<string>	An array of feature identifiers.
`catalogHrn`	string	A HERE Resource Name (HRN) for the catalog.
`layerId`	string	An identifier for the layer in the catalog.
`onResult`	function(H.service.ServiceResult)	A callback function to be called with a FeatureCollection object.
`onError`	function(Error)	A callback function to be called in case of failed request.
`opt_params`	H.service.ServiceParameters	optional Optional service parameters to be added to the request.

See:

Data API Guide - Get Data from an Interactive Map Layer - Get features by ID - Requesting multiple features

Throws:

If at least one of required arguments is not supplied or has a wrong type.

Returns:

Type	Description
H.util.ICancelable	A handle that allows to cancel the request.

getFeaturesByPointAndRadius (params, catalogHrn, layerId, onResult, onError)H.util.ICancelable

To retrieve a list of features in the layer, by center point and radius. A center point could be either specified directly or by referencing a feature (which could be from another layer).

Name	Type	Description
`params`	H.service.ServiceParameters	An object with `radius` and either `lat`+`lng` or `refCatalogHrn`+`refLayerId`+`refFeatureId` combination, together with other (optional) service parameters.
`catalogHrn`	string	A HERE Resource Name (HRN) for the catalog.
`layerId`	string	An identifier for the layer in the catalog.
`onResult`	function(H.service.ServiceResult)	A callback function to be called with a FeatureCollection object.
`onError`	function(Error)	A callback function to be called in case of failed request.

See:

Data API Reference - Get features with radius search

Throws:

If at least one of required arguments is not supplied or has a wrong type.

Returns:

Type	Description
H.util.ICancelable	A handle that allows to cancel the request.

Example

imlService.getFeaturesByPointAndRadius(
  {lat: 38.90192, lng: -76.97605, radius: 1000},
  'catalog_hrn_goes_here', 'layer_id_goes_here',
  console.log, console.error,
);

getFeaturesByTile (x, y, z, catalogHrn, layerId, onResult, onError, opt_params, opt_geojsonFormat)H.util.ICancelable

To request layer data by tile coordinates.

Name	Type	Description
`x`	number	Tile column number.
`y`	number	Tile row number.
`z`	number	Zoom level.
`catalogHrn`	string	A HERE Resource Name (HRN) for the catalog.
`layerId`	string	An identifier for the layer in the catalog.
`onResult`	function((ArrayBuffer\|H.service.ServiceResult))	A callback function to be called with either MVT or GeoJSON tile data, depending on the `opt_geojsonFormat` argument (MVT by default).
`onError`	function(Error)	A callback function to be called in case of failed request.
`opt_params`	H.service.ServiceParameters	optional Optional service parameters to be added to the request. The `clip` parameter is set to `true` by default.
`opt_geojsonFormat`	boolean	optional Defines whether to request features in GeoJSON (`true`) or MVT (`false`) format. Default value is `false`.

See:

Data API Guide - Get Data from an Interactive Map Layer - Get features in tile

Returns:

Type	Description
H.util.ICancelable	A handle that allows to cancel the request.

getStatistics (catalogHrn, layerId, onResult, onError, opt_params)H.util.ICancelable

To retrieve a statistical information about the layer.

Name	Type	Description
`catalogHrn`	string	A HERE Resource Name (HRN) for the catalog.
`layerId`	string	An identifier for the layer in the catalog.
`onResult`	function(H.service.ServiceResult)	A callback function to be called with an object containing statistical information about the layer.
`onError`	function(Error)	A callback function to be called in case of failed request.
`opt_params`	H.service.ServiceParameters	optional Optional service parameters to be added to the request.

See:

Data API Guide - Get Data from an Interactive Map Layer - Get statistics

Throws:

If at least one of required arguments is not supplied or has a wrong type.

Returns:

Type	Description
H.util.ICancelable	A handle that allows to cancel the request.

getUrl ()H.service.Url inherited

This method returns the configured service URL.

Returns:

Type	Description
H.service.Url

iterateFeatures (catalogHrn, layerId, onResult, onError, opt_params)H.util.ICancelable

To retrieve all features in the layer, in a paginated manner.

Name	Type	Description
`catalogHrn`	string	A HERE Resource Name (HRN) for the catalog.
`layerId`	string	An identifier for the layer in the catalog.
`onResult`	function(H.service.ServiceResult)	A callback function to be called with a FeatureCollection object.
`onError`	function(Error)	A callback function to be called in case of failed request.
`opt_params`	H.service.ServiceParameters	optional Optional service parameters to be added to the request.

See:

Data API Guide - Get Data from an Interactive Map Layer - Iterating features

Throws:

If at least one of required arguments is not supplied or has a wrong type.

Returns:

Type	Description
H.util.ICancelable	A handle that allows to cancel the request.

patchFeature (featureId, geojsonObject, catalogHrn, layerId, onResult, onError, opt_params)H.util.ICancelable

To update specific fields of an individual feature in the layer, preserving untouched fields. Creates a PATCH request with a given GeoJSON payload as its body.

Name	Type	Description
`featureId`	string	A feature identifier.
`geojsonObject`	Object	A GeoJSON `Feature` object to patch.
`catalogHrn`	string	A HERE Resource Name (HRN) for the catalog.
`layerId`	string	An identifier for the layer in the catalog.
`onResult`	function(H.service.ServiceResult)	A callback function to be called with a FeatureCollection object.
`onError`	function(Error)	A callback function to be called in case of failed request.
`opt_params`	H.service.ServiceParameters	optional Optional service parameters to be added to the request.

See:

Data API Reference - Patch a feature

Throws:

If at least one of required arguments is not supplied or has a wrong type.

Returns:

Type	Description
H.util.ICancelable	A handle that allows to cancel the request.

postFeatures (geojsonObject, catalogHrn, layerId, onResult, onError, opt_params)H.util.ICancelable

To create or update features in the layer. Creates a POST request with a given GeoJSON payload as its body. Keeps previously existing features in the layer.

Name	Type	Description
`geojsonObject`	Object	A GeoJSON object containing features to store.
`catalogHrn`	string	A HERE Resource Name (HRN) for the catalog.
`layerId`	string	An identifier for the layer in the catalog.
`onResult`	function(H.service.ServiceResult)	A callback function to be called with a FeatureCollection object.
`onError`	function(Error)	A callback function to be called in case of failed request.
`opt_params`	H.service.ServiceParameters	optional Optional service parameters to be added to the request.

See:

Data API Guide - Publish Data - Publish to an Interactive Map Layer

Throws:

If at least one of required arguments is not supplied or has a wrong type.

Returns:

Type	Description
H.util.ICancelable	A handle that allows to cancel the request.

putFeature (featureId, geojsonObject, catalogHrn, layerId, onResult, onError, opt_params)H.util.ICancelable

To create or replace an individual feature in the layers. Creates a PUT request with a given GeoJSON payload as its body.

Name	Type	Description
`featureId`	string	A feature identifier.
`geojsonObject`	Object	A GeoJSON `Feature` object to store.
`catalogHrn`	string	A HERE Resource Name (HRN) for the catalog.
`layerId`	string	An identifier for the layer in the catalog.
`onResult`	function(H.service.ServiceResult)	A callback function to be called with a FeatureCollection object.
`onError`	function(Error)	A callback function to be called in case of failed request.
`opt_params`	H.service.ServiceParameters	optional Optional service parameters to be added to the request.

See:

Data API Reference - Create or replace a feature

Throws:

If at least one of required arguments is not supplied or has a wrong type.

Returns:

Type	Description
H.util.ICancelable	A handle that allows to cancel the request.

putFeatures (geojsonObject, catalogHrn, layerId, onResult, onError, opt_params)H.util.ICancelable

To create or replace features in the layer. Creates a PUT request with a given GeoJSON payload as its body. Deletes all previously existing features in the layer.

Name	Type	Description
`geojsonObject`	Object	A GeoJSON object containing features to store.
`catalogHrn`	string	A HERE Resource Name (HRN) for the catalog.
`layerId`	string	An identifier for the layer in the catalog.
`onResult`	function(H.service.ServiceResult)	A callback function to be called with a FeatureCollection object.
`onError`	function(Error)	A callback function to be called in case of failed request.
`opt_params`	H.service.ServiceParameters	optional Optional service parameters to be added to the request.

See:

Data API Guide - Publish Data - Publish to an Interactive Map Layer

Throws:

If at least one of required arguments is not supplied or has a wrong type.

Returns:

Type	Description
H.util.ICancelable	A handle that allows to cancel the request.

removeEventListener (type, handler, opt_capture, opt_scope) inherited

This method removes a previously added listener from the EventTarget instance.

Name	Type	Description
`type`	string	The name of the event
`handler`	function	A previously added event handler
`opt_capture`	boolean	optional `true` indicates that the method should listen in the capture phase (bubble otherwise)
`opt_scope`	Object	optional An object defining the scope for the handler function

searchFeatures (catalogHrn, layerId, onResult, onError, opt_params)H.util.ICancelable

To search for features in the layer.

Name	Type	Description
`catalogHrn`	string	A HERE Resource Name (HRN) for the catalog.
`layerId`	string	An identifier for the layer in the catalog.
`onResult`	function(H.service.ServiceResult)	A callback function to be called with a FeatureCollection object.
`onError`	function(Error)	A callback function to be called in case of failed request.
`opt_params`	H.service.ServiceParameters	optional Optional service parameters to be added to the request.

See:

Data API Guide - Get Data from an Interactive Map Layer - Searching for features

Throws:

If at least one of required arguments is not supplied or has a wrong type.

Returns:

Type	Description
H.util.ICancelable	A handle that allows to cancel the request.

Type Definitions

H.service.iml.Service.Options Object

This type encapsulates configuration options for an instance of an IML service.

Properties:

Name	Type	Argument	Description
`baseUrl`	H.service.Url	<optional>	The base URL of the service. If supplied, it overrides all defaults (either coming from platform or service internals) including authentication params.
`subDomain`	string	<optional>	The subdomain of the IML service relative to the base URL.
`path`	string	<optional>	The path to use within the service URL.
`headers`	Object	<optional>	A map of HTTP headers to be sent with each request made by the service.
`getToken`	function		A callback function to return an access token. When provided, this function is called by each transport method of the service in order to supply `Authorization: Bearer {token}` request header.