Maps API for JavaScript Developer's Guide

H.service.extension.customLocation.Service

Class Summary

Extends: H.service.AbstractRestService

This class encapsulates the Custom Location Extension API ("CLE") in a service stub, providing methods to access its resources.

[ For full details, see the Class Details ]

Method Summary

Table 1. Methods
Methods

createTileLayer (layerConfig, options) : {(H.map.layer.TileLayer | H.map.layer.MarkerTileLayer)}

To create a tile layer which can be added to the map in order to visualize data from the specified CLE data layer.

request (entryPoint, entryPointType, params, onResult, onError) : {H.util.ICancelable}

This method sends a request to a resource with the provided name and type from the Custom Location Extension API. For available types see Constructing a Request.

getLayer (layerId, onResult, onError) : {H.util.ICancelable}

To fetch the meta information for a data layer from the CLE backend and create a Table instance, that represents the requested layer, to work with.

grantAccess (layerId, grants, onResult, onError) : {H.util.ICancelable}

To set the rights for other APP-IDs to access a CLE data layer. See Grant other app_ids Access to Geometry Layers for more details.

deleteLayer (layerId, onResult, onError) : {H.util.ICancelable}

To delete an existing data layer from the CLE backend.

createLayer (metaInfo, onResult, onError) : {H.util.ICancelable}

To create a new data layer on the CLE backend and to provide a Table instance, that represents the created layer, to work with. The operation fails (onError is triggered) if the layer already exists or the provided meta information contains invalid properties.

searchByProximity (layerIds, center, radius, onResult, onError, opt_params) : {H.util.ICancelable}

To search for CLE data layer entries that are within a given radius around a geographical center. See Proximity Search for more details.

searchByCorridor (layerIds, corridor, radius, onResult, onError, opt_params) : {H.util.ICancelable}

To search for CLE data layer entries that are within a given radius along a polyline. See Corridor Polygon Search for more details.

searchByBoundingBox (layerIds, bounds, onResult, onError, opt_params) : {H.util.ICancelable}

To search for CLE data layer entries within a rectangular geographical area. See Bounding Box Search for more details.

searchAll (layerId, onResult, onError, opt_params) : {H.util.ICancelable}

To search for CLE data layer entries It's possible to limit the resulting entries by different query parameters (see opt_params argument). See Attribute Search and Layer Download for more details).

appendRows (rows, onResult, onError) : {H.util.ICancelable}

To append rows to CLE data layers.

updateRows (rows, onResult, onError) : {H.util.ICancelable}

To update rows of CLE data layers.

deleteRows (rows, onResult, onError) : {H.util.ICancelable}

To delete rows from CLE data layer.

configure (appId, appCode, useHTTPS, useCIT, opt_baseUrl) : {H.service.IConfigurable}

This method receives configuration parameters from the platform, that can be used by the object implementing the interface. The method must not be invoked directly.

Class Description

This class encapsulates the Custom Location Extension API ("CLE") in a service stub, providing methods to access its resources.

An instance of this class can be retrieved by calling the factory method on a platform instance. H.service.Platform#getCustomLocationService.

Example

// Assumption: the platform is instantiated
customLocationService = platform.getCustomLocationService();

Constructor Details

H.service.extension.customLocation.Service(opt_options)

Parameters:
 
opt_options:
{H.service.extension.customLocation.Service.Options=} [optional]
 
The options to configure the service.

Method Details

createTileLayer (layerConfig, options) : {(H.map.layer.TileLayer | H.map.layer.MarkerTileLayer)}

To create a tile layer which can be added to the map in order to visualize data from the specified CLE data layer.

Example

// Assumption: The platform is already instantiated and a layer with ID "LAYER1" exists on the CLE backend:
cleService = platform.getCustomLocationService();

// Create a tile layer:
cleLayer = cleService.createTileLayer({layerId: 'LAYER1'}, {
  resultType: H.service.extension.TileProvider.ResultType.MARKER
});
// Add the tile layer to the map
map.addLayer(cleLayer);
Parameters:
 
layerConfig:
{H.service.extension.customLocation.LayerConfig}
 
The configuration for the data layer to load.
options:
{H.service.extension.TileProvider.Options}
 
The options to configure the tile provider.
Returns:
 
{(H.map.layer.TileLayer | H.map.layer.MarkerTileLayer)}
The created tile layer.

request (entryPoint, entryPointType, params, onResult, onError) : {H.util.ICancelable}

This method sends a request to a resource with the provided name and type from the Custom Location Extension API. For available types see Constructing a Request.

Example

// Fetching list of layers
// Assumption: the platform is instantiated
var service = platform.getCustomLocationService();
service.request(
  H.service.extension.customLocation.Service.EntryPoint.LAYERS_LIST,
  H.service.extension.customLocation.Service.EntryPointType.JSON, {},
  console.log, console.error);
Parameters:
 
entryPoint:
{H.service.extension.customLocation.Service.EntryPoint}
 
The entry point of the CLE API.
entryPointType:
{H.service.extension.customLocation.Service.EntryPointType}
 
The type of the response for the entry point.
params:
{H.service.ServiceParameters}
 
A key-value map of query parameters to use for the request.
onResult:
{function(H.service.ServiceResult)}
 
The callback which is called when result is returned
onError:
{function(Error)}
 
The callback which is called when error occurred (i.e request timeout, or server error)
Returns:
 
{H.util.ICancelable}
a handle that allows to cancel the request.
Throws:
 
{H.lang.InvalidArgumentError}
 
If passed arguments are invalid

getLayer (layerId, onResult, onError) : {H.util.ICancelable}

To fetch the meta information for a data layer from the CLE backend and create a Table instance, that represents the requested layer, to work with.

Parameters:
 
layerId:
{string}
 
The ID of the requested layer.
onResult:
{function(H.service.extension.customLocation.Table)}
 
The callback to invoke if the meta information could be fetched. It gets a Table, that represents the requested data layer, as argument.
onError:
{function(Error)}
 
The callback to invoke if an error occurs.
Returns:
 
{H.util.ICancelable}
a handle that allows to cancel the request.

grantAccess (layerId, grants, onResult, onError) : {H.util.ICancelable}

To set the rights for other APP-IDs to access a CLE data layer. See Grant other app_ids Access to Geometry Layers for more details.

Parameters:
 
layerId:
{string}
 
The ID of the layer.
grants:
{!Array<!H.service.extension.customLocation.Grant>}
 
The grants for other App-IDs to access the layer.
onResult:
{function(H.service.extension.customLocation.Table)}
 
The callback to invoke if the access is granted.
onError:
{function(Error)}
 
The callback to invoke if an error occurs.
Returns:
 
{H.util.ICancelable}
a handle that allows to cancel the request.

deleteLayer (layerId, onResult, onError) : {H.util.ICancelable}

To delete an existing data layer from the CLE backend.

Parameters:
 
layerId:
{string}
 
The ID of the data layer to delete.
onResult:
{function(H.service.ServiceResult)}
 
The callback to invoke if the layer could be deleted.
onError:
{function(Error)}
 
The callback to invoke if an error occurs.
Returns:
 
{H.util.ICancelable}
a handle that allows to cancel the delete request.

createLayer (metaInfo, onResult, onError) : {H.util.ICancelable}

To create a new data layer on the CLE backend and to provide a Table instance, that represents the created layer, to work with. The operation fails (onError is triggered) if the layer already exists or the provided meta information contains invalid properties.

Parameters:
 
metaInfo:
{!H.service.extension.customLocation.MetaInfo}
 
The meta information for the layer
onResult:
{function(H.service.extension.customLocation.Table)}
 
The callback to invoke when the layer could be created.
onError:
{function(Error)}
 
The callback to invoke if an error occurs.
Returns:
 
{H.util.ICancelable}
a handle that allows to cancel the create request.
Throws:
 
{H.lang.InvalidArgumentError}
 
if the provided meta information or one of the callbacks is invalid.

searchByProximity (layerIds, center, radius, onResult, onError, opt_params) : {H.util.ICancelable}

To search for CLE data layer entries that are within a given radius around a geographical center. See Proximity Search for more details.

Parameters:
 
layerIds:
{Array<string>}
 
The IDs of the layers to search in.
center:
{H.geo.Point}
 
The geographical point to search around.
radius:
{number}
 
The search radius in meters.
onResult:
{function(Array<H.service.extension.customLocation.Table.Row>, boolean)}
 
The callback to invoke when a chunk of data is received. The following arguments are passed:
  1. The list of received entries of the CLE data layer.
  2. An indicator whether it's the last chunk.
onError:
{function(Error)}
 
The callback to invoke when an error ocurred.
opt_params:
{H.service.ServiceParameters=} [optional]
 
A key-value map of query parameters to use for the search (see CLE documentation for more details). A query parameter has a higher priority than a value provided by an according method argument.
Returns:
 
{H.util.ICancelable}
a handle that allows to cancel the search request.
Throws:
 
{H.lang.InvalidArgumentError}
 
if the passed parameters have invalid type.

searchByCorridor (layerIds, corridor, radius, onResult, onError, opt_params) : {H.util.ICancelable}

To search for CLE data layer entries that are within a given radius along a polyline. See Corridor Polygon Search for more details.

Parameters:
 
layerIds:
{Array<string>}
 
The IDs of the layers to search in.
corridor:
{(H.geo.LineString | string)}
 
The center line of the corridor. Either defined as a H.geo.LineString or as a RouteId string that was obtained from a previous Router call. See H.service.RoutingService#calculateRoute or Routing API CalculateRouteResponseType.
radius:
{number}
 
The radius of the corridor in meters.
onResult:
{function(Array<H.service.extension.customLocation.Table.Row>, boolean)}
 
The callback to invoke when a chunk of data is received. The following arguments are passed:
  1. The list of received entries of the CLE data layer.
  2. An indicator whether it's the last chunk.
onError:
{function(Error)}
 
The callback to invoke when an error ocurred.
opt_params:
{H.service.ServiceParameters=} [optional]
 
A key-value map of query parameters to use for the search. A query parameter has a higher priority than a value provided by an according method argument.
Returns:
 
{H.util.ICancelable}
a handle that allows to cancel the search request.
Throws:
 
{H.lang.InvalidArgumentError}
 
if the passed parameters have invalid type.

searchByBoundingBox (layerIds, bounds, onResult, onError, opt_params) : {H.util.ICancelable}

To search for CLE data layer entries within a rectangular geographical area. See Bounding Box Search for more details.

Parameters:
 
layerIds:
{Array<string>}
 
The IDs of the layers to search in.
bounds:
{H.geo.Rect}
 
The geographical area where to search.
onResult:
{function(Array<H.service.extension.customLocation.Table.Row>, boolean)}
 
The callback to invoke when a chunk of data is received. The following arguments are passed:
  1. The list of received entries of the CLE data layer.
  2. An indicator whether it's the last chunk.
onError:
{function(Error)}
 
The callback to invoke when an error ocurred.
opt_params:
{H.service.ServiceParameters=} [optional]
 
A key-value map of query parameters to use for the search. A query parameter has a higher priority than a value provided by an according method argument.
Returns:
 
{H.util.ICancelable}
a handle that allows to cancel the search request.
Throws:
 
{H.lang.InvalidArgumentError}
 
if the passed parameters have invalid type.

searchAll (layerId, onResult, onError, opt_params) : {H.util.ICancelable}

To search for CLE data layer entries It's possible to limit the resulting entries by different query parameters (see opt_params argument). See Attribute Search and Layer Download for more details).

Parameters:
 
layerId:
{!string}
 
The ID of the data layer to download.
onResult:
{function(Array<H.service.extension.customLocation.Table.Row>, boolean)}
 
The callback to invoke when a chunk of data is received. The following arguments are passed:
  1. The list of received entries of the CLE data layer.
  2. An indicator whether it's the last chunk.
onError:
{function(Error)}
 
The callback to invoke when an error ocurred.
opt_params:
{H.service.ServiceParameters=} [optional]
 
A key-value map of query parameters to use for the search. A query parameter has a higher priority than a value provided by an according method argument.
Returns:
 
{H.util.ICancelable}
a handle to the request that allows to cancel it.
Throws:
 
{H.lang.InvalidArgumentError}
 
if the passed parameters have invalid type.

appendRows (rows, onResult, onError) : {H.util.ICancelable}

To append rows to CLE data layers.

Example

function onResult(table) {
  var row = table.addRow();
  row.setCell('COMPANY', 'HERE Technologies');
  row.setCell('WKT', new H.geo.Point(52.5309, 13.3849));
  cleService.appendRows([row], console.log, console.error);
}
cleService.getLayer('MY_LAYER', onResult, console.error);
Parameters:
 
rows:
{!Array<!H.service.extension.customLocation.Table.Row>}
 
The data rows to append. All rows must have a GEOMETRY_ID cell whose value is null or an empty string.
onResult:
{function(!Array<!H.service.extension.customLocation.Table.Row>, boolean)}
 
The callback to invoke when a chunk is processed. The following arguments are passed:
  • The list of processed rows.
  • An indicator whether it's the last chunk.
onError:
{function(Error, !Array<!H.service.extension.customLocation.Table.Row>, boolean)}
 
The callback to invoke when an error ocurred. The following arguments are passed:
  • The ocurred error.
  • The list of rows of the chunk which caused the error.
  • An indicator whether it's the last chunk.
Returns:
 
{H.util.ICancelable}
a handle that allows to cancel the delete request.
Throws:
 
{H.lang.InvalidArgumentError}
 
if rows with defined GEOMETRY_ID are passed or if the onResult or onError callback is not valid.

updateRows (rows, onResult, onError) : {H.util.ICancelable}

To update rows of CLE data layers.

Example

// Precondition: There is only one entry in the layer that has a COMPANY value of "HERE Technologies"
function onResult(rows, isLastChunk) {
  var row = rows[0];
  row.setCell("WKT", new H.geo.Point(52.5309, 13.3849));
  cleService.updateRows([row], console.log, console.error);
}
cleService.searchAll("MY_LAYER', onResult, console.error, {filter: 'COMPANY === "HERE Technologies"'})
Parameters:
 
rows:
{!Array<!H.service.extension.customLocation.Table.Row>}
 
The data rows to update. All rows must have an defined GEOMETRY_ID cell.
onResult:
{function(!Array<!H.service.extension.customLocation.Table.Row>, boolean)}
 
The callback to invoke when a chunk is processed. The following arguments are passed:
  • The list of processed rows.
  • An indicator whether it's the last chunk.
onError:
{function(Error, !Array<!H.service.extension.customLocation.Table.Row>, boolean)}
 
The callback to invoke when an error ocurred. The following arguments are passed:
  • The ocurred error.
  • The list of rows of the chunk which caused the error.
  • An indicator whether it's the last chunk.
Returns:
 
{H.util.ICancelable}
a handle that allows to cancel the delete request.
Throws:
 
{H.lang.InvalidArgumentError}
 
if several rows with the same "GEOMETRY_ID" have been passed, if rows without defined GEOMETRY_ID are passed or if the onResult or onError callback is not valid.

deleteRows (rows, onResult, onError) : {H.util.ICancelable}

To delete rows from CLE data layer.

Example

// Precondition: There is only one entry in the layer that has a COMPANY value of "HERE Technologies"
function onResult(rows, isLastChunk) {
  cleService.deleteRows(rows, console.log, console.error);
}
cleService.searchAll("MY_LAYER', onResult, console.error, {filter: 'COMPANY === "HERE Technologies"'})
Parameters:
 
rows:
{!Array<!H.service.extension.customLocation.Table.Row>}
 
The data rows to delete. All rows must have a defined GEOMETRY_ID cell.
onResult:
{function(!Array<!H.service.extension.customLocation.Table.Row>, boolean)}
 
The callback to invoke when a chunk is processed. The following arguments are passed:
  • The list of processed rows.
  • An indicator whether it's the last chunk.
onError:
{function(Error, !Array<!H.service.extension.customLocation.Table.Row>, boolean)}
 
The callback to invoke when an error ocurred. The following arguments are passed:
  • The ocurred error.
  • The list of rows of the chunk which caused the error.
  • An indicator whether it's the last chunk.
Returns:
 
{H.util.ICancelable}
a handle that allows to cancel the delete request.
Throws:
 
{H.lang.InvalidArgumentError}
 
if several rows with the same "GEOMETRY_ID" have been passed, if rows without defined GEOMETRY_ID are passed or if the onResult or onError callback is not valid.

configure (appId, appCode, useHTTPS, useCIT, opt_baseUrl) : {H.service.IConfigurable}

This method receives configuration parameters from the platform, that can be used by the object implementing the interface. The method must not be invoked directly.

Example

// assuming that the configurable object exists and the variable name is "configurable"
var platform = new H.service.Platform({
  'app_id': [your app_id],
  'app_code': [your app_code],
})
platform.configure(configurable);
Parameters:
 
appId:
{string}
 
The application ID to identify the client against the platform (mandatory)
appCode:
{string}
 
The application code to identify the client against the platform (mandatory)
useHTTPS:
{boolean}
 
The indicator whether secure communication is used (true), the default is false
useCIT:
{boolean}
 
A value indicating whether Customer Integration Testing ("CIT") is used (true), the default is false
opt_baseUrl:
{H.service.Url=} [optional]
 
The base URL of the platform, the default is http://api.here.com. Note that if the useHTTPS flag is set to true, the URL scheme specified in the opt_baseUrl is overridden to use HTTPS.
Returns:
 
{H.service.IConfigurable}
An instance of IConfigurable reflecting the new configuration