here_location_services.ls module

This module contains class to interact with Location services REST APIs.

class here_location_services.ls.LS(api_key=None, platform_credentials=None, proxies=None, country='row')[source]

Bases: object

A single interface for the user to interact with rest of the Location services APIs.

Parameters
__init__(api_key=None, platform_credentials=None, proxies=None, country='row')[source]
Parameters
geocode(query, limit=20, lang='en-US')[source]

Calculate coordinates as result of geocoding for the given query.

Parameters

  • query (str) – A string containing the input query.

  • limit (int) – An int representing maximum number of results to be returned. Default value is 20.

  • lang (str) – A string to represent language to be used for result rendering from a list of BCP47 compliant Language Codes.

Raises

ValueError – If query is empty or having all whitespace characters.

Returns

GeocoderResponse object.

Return type

here_location_services.responses.GeocoderResponse

reverse_geocode(lat, lng, limit=1, lang='en-US')[source]

Return the address label string as the result of reverse-geocoding the given latitude and longitude.

Parameters

  • lat (float) – A float representing latitude of point.

  • lng (float) – A float representing longitude of point.

  • limit (int) – An int representing maximum number of results to be returned. Default value is 1.

  • lang (str) – A string to represent language to be used for result rendering from a list of BCP47 compliant Language Codes.

Raises

ValueError – If Latitude is not in range between -90 and 90 or Longitude is not in range between -180 and 180.

Returns

ReverseGeocoderResponse object.

Return type

here_location_services.responses.ReverseGeocoderResponse

calculate_isoline(range, range_type, transport_mode, origin=None, departure_time=None, destination=None, arrival_time=None, routing_mode='fast', shape_max_points=None, optimised_for='balanced', avoid_features=None, truck=None, origin_place_options=None, origin_waypoint_options=None, destination_place_options=None, destination_waypoint_options=None)[source]

Calculate isoline routing.

Request a polyline that connects the endpoints of all routes leaving from one defined center with either a specified length or specified travel time.

Parameters

  • range (str) – A string representing a range of isoline, unit is defined by parameter range type. Example: range=’1000’ or range=’1000,2000,3000’

  • range_type (str) – A string representing a type of range. Possible values are distance, time and consumption. For distance the unit meters. For a time the unit is seconds. For consumption, it is defined by the consumption model.

  • transport_mode (str) – A string representing Mode of transport to be used for the calculation of the isolines. Example: car.

  • origin (Optional[List]) – Center of the isoline request. The Isoline(s) will cover the region which can be reached from this point within given range. It cannot be used in combination with destination parameter.

  • departure_time (Optional[datetime.datetime]) – Specifies the time of departure as defined by either date-time or full-date partial-time in RFC 3339, section 5.6 (for example, 2019-06-24T01:23:45). The requested time is converted to the local time at origin. When the optional timezone offset is not specified, time is assumed to be local. If neither departure_time or arrival_time are specified, current time at departure location will be used. All Time values in the response are returned in the timezone of each location.

  • destination (Optional[List]) – Center of the isoline request. The Isoline(s) will cover the region within the specified range that can reach this point. It cannot be used in combination with origin parameter.

  • arrival_time (Optional[datetime.datetime]) – Specifies the time of arrival as defined by either date-time or full-date T partial-time in RFC 3339, section 5.6 (for example, 2019-06-24T01:23:45). The requested time is converted to the local time at destination. When the optional timezone offset is not specified, time is assumed to be local. All Time values in the response are returned in the timezone of each location.

  • routing_mode (Optional[str]) – A string to represent routing mode.

  • shape_max_points (Optional[int]) – An integer to Limit the number of points in the resulting isoline geometry. If the isoline consists of multiple components, the sum of points from all components is considered. This parameter doesn’t affect performance.

  • optimised_for (Optional[str]) – A string to specify how isoline calculation is optimized.

  • avoid_features (Optional[List[str]]) – Avoid routes that violate these properties. Avoid features are defined in :attr: AVOID_FEATURES <here_location_services.config.isoline_routing_config.AVOID_FEATURES>

  • truck (Optional[here_location_services.config.base_config.Truck]) – Different truck options to use during route calculation when transport_mode = truck. use object of Truck here_location_services.config.base_config.Truck>

  • origin_place_options (Optional[here_location_services.config.base_config.PlaceOptions]) – PlaceOptions optinal place options for origin.

  • origin_waypoint_options (Optional[here_location_services.config.base_config.WayPointOptions]) – WayPointOptions optional waypoint options for origin.

  • destination_place_options (Optional[here_location_services.config.base_config.PlaceOptions]) – PlaceOptions optinal place options for destination.

  • destination_waypoint_options (Optional[here_location_services.config.base_config.WayPointOptions]) – WayPointOptions optional waypoint options for destination.

Raises

ValueError – If origin and destination are provided together.

Returns

IsolineResponse object.

Return type

here_location_services.responses.IsolineResponse

autosuggest(query, at=None, search_in_circle=None, search_in_bbox=None, in_country=None, limit=20, terms_limit=None, lang=None, political_view=None, show=None)[source]

Suggest address or place candidates based on an incomplete or misspelled query

Parameters

  • query (str) – A string for free-text query. Example: res, rest

  • at (Optional[List]) – Specify the center of the search context expressed as list of coordinates One of at, search_in_circle or search_in_bbox is required. Parameters “at”, “search_in_circle” and “search_in_bbox” are mutually exclusive. Only one of them is allowed.

  • search_in_circle (Optional[here_location_services.config.autosuggest_config.SearchCircle]) – Search within a circular geographic area provided as latitude, longitude, and radius (in meters)

  • search_in_bbox (Optional[Tuple]) – Search within a rectangular bounding box geographic area provided as tuple of west longitude, south latitude, east longitude, north latitude

  • in_country (Optional[List[str]]) – Search within a specific or multiple countries provided as comma-separated ISO 3166-1 alpha-3 country codes. The country codes are to be provided in all uppercase. Must be accompanied by exactly one of at, search_in_circle or search_in_bbox.

  • limit (Optional[int]) – An integer specifiying maximum number of results to be returned.

  • terms_limit (Optional[int]) – An integer specifiying maximum number of Query Terms Suggestions to be returned.

  • lang (Optional[List[str]]) – List of strings to select the language to be used for result rendering from a list of BCP 47 compliant language codes.

  • political_view (Optional[str]) – Toggle the political view.

  • show (Optional[List[str]]) – Select additional fields to be rendered in the response. Please note that some of the fields involve additional webservice calls and can increase the overall response time.

Returns

requests.Response object.

Raises

ValueError – If search_in_circle,``search_in_bbox`` and destination are provided together.

Return type

here_location_services.responses.AutosuggestResponse

get_dest_weather(products, at=None, query=None, zipcode=None, hourly_date=None, one_observation=None, language=None, units=None)[source]
Retrieves weather reports, weather forecasts, severe weather alerts

and moon and sun rise and set information.

Parameters

  • products (List[str]) – List of DestWeatherProduct identifying the type of report to obtain.

  • at (Optional[List]) – A list of latitude and longitude specifying the area covered by the weather report.

  • query (Optional[str]) – Free text query. Examples: “125, Berliner, berlin”, “Beacon, Boston”

  • zipcode (Optional[str]) – ZIP code of the location. This parameter is supported only for locations in the United States of America.

  • hourly_date (Optional[Union[datetime.date, datetime.datetime]]) – Date for which hourly forecasts are to be retrieved. Can be either a date or datetime object

  • one_observation (Optional[bool]) – Boolean, if set to true, the response only includes the closest location. Only available when the product parameter is set to DEST_WEATHER_PRODUCT.observation.

  • language (Optional[str]) – Defines the language used in the descriptions in the response.

  • units (Optional[str]) – Defines whether units or imperial units are used in the response.

Raises

  • ValueError – If neither at, query or zipcode are passed.

  • ValueError – If one_observation is set to true without passing DEST_WEATHER_PRODUCT.observation in products

Returns

DestinationWeatherResponse object.

Return type

here_location_services.responses.DestinationWeatherResponse

get_weather_alerts(geometry, start_time, id=None, weather_severity=None, weather_type=None, country=None, end_time=None, width=None)[source]
Retrieves weather reports, weather forecasts, severe weather alerts

and moon and sun rise and set information.

Parameters

  • geometry (Union[geojson.geometry.Point, geojson.geometry.LineString]) – Point or LineString defining the route or a single location

  • start_time (datetime.datetime) – Start time of the event

  • id (Optional[str]) – Unique weather alert id.

  • weather_severity (Optional[int]) – Defines the severity of the weather event as defined in WeatherSeverity.

  • weather_type (Optional[str]) – Defines the type of the weather event as defined in WeatherType.

  • country (Optional[str]) – String for ISO-3166-1 2-letter country code.

  • end_time (Optional[datetime.datetime]) – End time of the event. If not present, warning is valid until it is not removed from the feed by national weather institutes (valid until warning is present in the response)

  • width (Optional[int]) – int

Raises

ValueError – If maximum width exceeds 100000 for point type geometry or width exceeds 25000 for LineString geometry

Returns

WeatherAlertsResponse object.

Return type

here_location_services.responses.WeatherAlertsResponse

solve_tour_planning(fleet, plan, id=None, optimization_traffic=None, optimization_waiting_time=None, is_async=False)[source]

Requests profile-aware routing data, creates a Vehicle Routing Problem and solves it.

Parameters

  • fleet (here_location_services.config.tour_planning_config.Fleet) – A fleet represented by various vehicle types for serving jobs.

  • plan (here_location_services.config.tour_planning_config.Plan) – Represents the list of jobs to be served.

  • id (Optional[str]) – A unique identifier of an entity. Avoid referencing any confidential or personal information as part of the Id.

  • optimization_traffic (Optional[str]) – “liveOrHistorical” “historicalOnly” “automatic” Specifies what kind of traffic information should be considered for routing

  • optimization_waiting_time (Optional[Dict]) – Configures departure time optimization which tries to adapt the starting time of the tour in order to reduce waiting time as a consequence of a vehicle arriving at a stop before the starting time of the time window defined for serving the job.

  • is_async (Optional[bool]) – Solves the problem Asynchronously

Raises

ApiError – If

Returns

TourPlanningResponse object.

Return type

here_location_services.responses.TourPlanningResponse

discover(query, center=None, radius=None, country_codes=None, bounding_box=None, limit=None, lang=None)[source]

Search places using Location Services discover endpoint.

This method uses location services discover endpoint to search places based on query which is free-form text. There are three different combination of inputs as shown below to search places using discover:

  • center and country_code

  • center and radius

  • bounding_box

Parameters

  • query (str) – A string representing free-text query to search places.

  • center (Optional[List[float]]) – A list of latitude and longitude representing the center for search query.

  • radius (Optional[int]) – A radius in meters along with center for searching places.

  • country_codes (Optional[List]) – A list of ISO 3166-1 alpha-3 country codes.

  • bounding_box (Optional[List[float]]) – A bounding box, provided as west longitude, south latitude, east longitude, north latitude.

  • limit (Optional[int]) – An int representing maximum number of results to be returned.

  • lang (Optional[str]) – A string to represent language to be used for result rendering from a list of BCP47 compliant Language Codes.

Raises

ValueError – If center and bounding_box are provided together.

Returns

DiscoverResponse object.

Return type

here_location_services.responses.DiscoverResponse

browse(center, radius=None, country_codes=None, bounding_box=None, categories=None, limit=None, name=None, lang=None)[source]

Get search results for places based on different filters such as categories or name.

Parameters

  • center (List) – A list of latitude and longitude representing the center for search query.

  • radius (Optional[int]) – A radius in meters along with center for searching places.

  • country_codes (Optional[List]) – A list of ISO 3166-1 alpha-3 country codes.

  • bounding_box (Optional[List[float]]) – A bounding box, provided as west longitude, south latitude, east longitude, north latitude.

  • categories (Optional[List]) – A list strings of category-ids.

  • limit (Optional[int]) – An int representing maximum number of results to be returned.

  • name (Optional[str]) – A string representing Full-text filter on POI names/titles.

  • lang (Optional[str]) – A string to represent language to be used for result rendering from a list of BCP47 compliant Language Codes.

Returns

BrowseResponse object.

Return type

here_location_services.responses.BrowseResponse

lookup(location_id, lang=None)[source]

Get search results by providing location_id.

Parameters

  • location_id (str) – A string representing id.

  • lang (Optional[str]) – A string to represent language to be used for result rendering from a list of BCP47 compliant Language Codes.

Returns

LookupResponse object.

Return type

here_location_services.responses.LookupResponse

car_route(origin, destination, via=None, origin_place_options=None, origin_waypoint_options=None, destination_place_options=None, destination_waypoint_options=None, departure_time=None, routing_mode='fast', alternatives=0, units='metric', lang='en-US', return_results=None, spans=None, avoid_features=None, avoid_areas=None, exclude=None)[source]

Calculate car route between two endpoints.

Parameters

  • origin (List) – A list of latitude and longitude of origin point of route.

  • destination (List) – A list of latitude and longitude of destination point of route.

  • via (Optional[List[here_location_services.config.routing_config.Via]]) – A list of Via objects.

  • origin_place_options (Optional[here_location_services.config.base_config.PlaceOptions]) – PlaceOptions optinal place options for origin.

  • origin_waypoint_options (Optional[here_location_services.config.base_config.WayPointOptions]) – WayPointOptions optional waypoint options for origin.

  • destination_place_options (Optional[here_location_services.config.base_config.PlaceOptions]) – PlaceOptions optinal place options for destination.

  • destination_waypoint_options (Optional[here_location_services.config.base_config.WayPointOptions]) – WayPointOptions optional waypoint options for destination.

  • departure_time (Optional[datetime.datetime]) – datetime.datetime object.

  • routing_mode (str) – A string to represent routing mode. use config defined in ROUTING_MODE

  • alternatives (int) – Number of alternative routes to return aside from the optimal route. default value is 0 and maximum is 6.

  • units (str) – A string representing units of measurement used in guidance instructions. The default is metric.

  • lang (str) – A string representing preferred language of the response. The value should comply with the IETF BCP 47.

  • return_results (Optional[List]) – A list of strings.

  • spans (Optional[List]) – A list of strings to define which attributes are included in the response spans. use config defined in ROUTING_SPANS

  • avoid_features (Optional[List[str]]) – Avoid routes that violate these properties. Avoid features are defined in AVOID_FEATURES

  • avoid_areas (Optional[List[here_location_services.config.matrix_routing_config.AvoidBoundingBox]]) – A list of areas to avoid during route calculation. To define avoid area.

  • exclude (Optional[List[str]]) – A comma separated list of three-letter country codes (ISO-3166-1 alpha-3 code) that routes will exclude.

Returns

RoutingResponse object.

Return type

here_location_services.responses.RoutingResponse

bicycle_route(origin, destination, via=None, origin_place_options=None, origin_waypoint_options=None, destination_place_options=None, destination_waypoint_options=None, departure_time=None, routing_mode='fast', alternatives=0, units='metric', lang='en-US', return_results=None, spans=None, avoid_features=None, avoid_areas=None, exclude=None)[source]

Calculate bicycle route between two endpoints.

Parameters

  • origin (List) – A list of latitude and longitude of origin point of route.

  • destination (List) – A list of latitude and longitude of destination point of route.

  • via (Optional[List[here_location_services.config.routing_config.Via]]) – A list of Via objects.

  • origin_place_options (Optional[here_location_services.config.base_config.PlaceOptions]) – PlaceOptions optinal place options for origin.

  • origin_waypoint_options (Optional[here_location_services.config.base_config.WayPointOptions]) – WayPointOptions optional waypoint options for origin.

  • destination_place_options (Optional[here_location_services.config.base_config.PlaceOptions]) – PlaceOptions optinal place options for destination.

  • destination_waypoint_options (Optional[here_location_services.config.base_config.WayPointOptions]) – WayPointOptions optional waypoint options for destination.

  • departure_time (Optional[datetime.datetime]) – datetime.datetime object.

  • routing_mode (str) – A string to represent routing mode.

  • alternatives (int) – Number of alternative routes to return aside from the optimal route. default value is 0 and maximum is 6.

  • units (str) – A string representing units of measurement used in guidance instructions. The default is metric.

  • lang (str) – A string representing preferred language of the response. The value should comply with the IETF BCP 47.

  • return_results (Optional[List]) – A list of strings.

  • spans (Optional[List]) – A list of strings to define which attributes are included in the response spans.

  • avoid_features (Optional[List[str]]) – Avoid routes that violate these properties. Avoid features are defined in AVOID_FEATURES

  • avoid_areas (Optional[List[here_location_services.config.matrix_routing_config.AvoidBoundingBox]]) – A list of areas to avoid during route calculation. To define avoid area.

  • exclude (Optional[List[str]]) – A comma separated list of three-letter country codes (ISO-3166-1 alpha-3 code) that routes will exclude.

Returns

RoutingResponse object.

Return type

here_location_services.responses.RoutingResponse

truck_route(origin, destination, via=None, origin_place_options=None, origin_waypoint_options=None, destination_place_options=None, destination_waypoint_options=None, departure_time=None, routing_mode='fast', alternatives=0, units='metric', lang='en-US', return_results=None, spans=None, truck=None, avoid_features=None, avoid_areas=None, exclude=None)[source]

Calculate truck route between two endpoints.

Parameters

  • origin (List) – A list of latitude and longitude of origin point of route.

  • destination (List) – A list of latitude and longitude of destination point of route.

  • via (Optional[List[here_location_services.config.routing_config.Via]]) – A list of Via objects.

  • origin_place_options (Optional[here_location_services.config.base_config.PlaceOptions]) – PlaceOptions optinal place options for origin.

  • origin_waypoint_options (Optional[here_location_services.config.base_config.WayPointOptions]) – WayPointOptions optional waypoint options for origin.

  • destination_place_options (Optional[here_location_services.config.base_config.PlaceOptions]) – PlaceOptions optinal place options for destination.

  • destination_waypoint_options (Optional[here_location_services.config.base_config.WayPointOptions]) – WayPointOptions optional waypoint options for destination.

  • departure_time (Optional[datetime.datetime]) – datetime.datetime object.

  • routing_mode (str) – A string to represent routing mode.

  • alternatives (int) – Number of alternative routes to return aside from the optimal route. default value is 0 and maximum is 6.

  • units (str) – A string representing units of measurement used in guidance instructions. The default is metric.

  • lang (str) – A string representing preferred language of the response. The value should comply with the IETF BCP 47.

  • return_results (Optional[List]) – A list of strings.

  • spans (Optional[List]) – A list of strings to define which attributes are included in the response spans.

  • truck (Optional[here_location_services.config.base_config.Truck]) – Different truck options to use during route calculation. use object of Truck here_location_services.config.matrix_routing_config.Truck>

  • avoid_features (Optional[List[str]]) – Avoid routes that violate these properties. Avoid features are defined in AVOID_FEATURES

  • avoid_areas (Optional[List[here_location_services.config.matrix_routing_config.AvoidBoundingBox]]) – A list of areas to avoid during route calculation. To define avoid area.

  • exclude (Optional[List[str]]) – A comma separated list of three-letter country codes (ISO-3166-1 alpha-3 code) that routes will exclude.

Returns

RoutingResponse object.

Return type

here_location_services.responses.RoutingResponse

scooter_route(origin, destination, via=None, origin_place_options=None, origin_waypoint_options=None, destination_place_options=None, destination_waypoint_options=None, scooter=None, departure_time=None, routing_mode='fast', alternatives=0, units='metric', lang='en-US', return_results=None, spans=None, avoid_features=None, avoid_areas=None, exclude=None)[source]

Calculate scooter route between two endpoints.

Parameters

  • origin (List) – A list of latitude and longitude of origin point of route.

  • destination (List) – A list of latitude and longitude of destination point of route.

  • via (Optional[List[here_location_services.config.routing_config.Via]]) – A list of Via objects.

  • origin_place_options (Optional[here_location_services.config.base_config.PlaceOptions]) – PlaceOptions optinal place options for origin.

  • origin_waypoint_options (Optional[here_location_services.config.base_config.WayPointOptions]) – WayPointOptions optional waypoint options for origin.

  • destination_place_options (Optional[here_location_services.config.base_config.PlaceOptions]) – PlaceOptions optinal place options for destination.

  • destination_waypoint_options (Optional[here_location_services.config.base_config.WayPointOptions]) – WayPointOptions optional waypoint options for destination.

  • scooter (Optional[here_location_services.config.routing_config.Scooter]) – Additional attributes for scooter route.

  • departure_time (Optional[datetime.datetime]) – datetime.datetime object.

  • routing_mode (str) – A string to represent routing mode.

  • alternatives (int) – Number of alternative routes to return aside from the optimal route. default value is 0 and maximum is 6.

  • units (str) – A string representing units of measurement used in guidance instructions. The default is metric.

  • lang (str) – A string representing preferred language of the response. The value should comply with the IETF BCP 47.

  • return_results (Optional[List]) – A list of strings.

  • spans (Optional[List]) – A list of strings to define which attributes are included in the response spans.

  • avoid_features (Optional[List[str]]) – Avoid routes that violate these properties. Avoid features are defined in AVOID_FEATURES

  • avoid_areas (Optional[List[here_location_services.config.matrix_routing_config.AvoidBoundingBox]]) – A list of areas to avoid during route calculation. To define avoid area.

  • exclude (Optional[List[str]]) – A comma separated list of three-letter country codes (ISO-3166-1 alpha-3 code) that routes will exclude.

Returns

RoutingResponse object.

Return type

here_location_services.responses.RoutingResponse

pedestrian_route(origin, destination, via=None, origin_place_options=None, origin_waypoint_options=None, destination_place_options=None, destination_waypoint_options=None, departure_time=None, routing_mode='fast', alternatives=0, units='metric', lang='en-US', return_results=None, spans=None, avoid_features=None, avoid_areas=None, exclude=None)[source]

Calculate pedestrian route between two endpoints.

Parameters

  • origin (List) – A list of latitude and longitude of origin point of route.

  • destination (List) – A list of latitude and longitude of destination point of route.

  • via (Optional[List[here_location_services.config.routing_config.Via]]) – A list of Via objects.

  • origin_place_options (Optional[here_location_services.config.base_config.PlaceOptions]) – PlaceOptions optinal place options for origin.

  • origin_waypoint_options (Optional[here_location_services.config.base_config.WayPointOptions]) – WayPointOptions optional waypoint options for origin.

  • destination_place_options (Optional[here_location_services.config.base_config.PlaceOptions]) – PlaceOptions optinal place options for destination.

  • destination_waypoint_options (Optional[here_location_services.config.base_config.WayPointOptions]) – WayPointOptions optional waypoint options for destination.

  • departure_time (Optional[datetime.datetime]) – datetime.datetime object.

  • routing_mode (str) – A string to represent routing mode.

  • alternatives (int) – Number of alternative routes to return aside from the optimal route. default value is 0 and maximum is 6.

  • units (str) – A string representing units of measurement used in guidance instructions. The default is metric.

  • lang (str) – A string representing preferred language of the response. The value should comply with the IETF BCP 47.

  • return_results (Optional[List]) – A list of strings.

  • spans (Optional[List]) – A list of strings to define which attributes are included in the response spans.

  • avoid_features (Optional[List[str]]) – Avoid routes that violate these properties. Avoid features are defined in AVOID_FEATURES

  • avoid_areas (Optional[List[here_location_services.config.matrix_routing_config.AvoidBoundingBox]]) – A list of areas to avoid during route calculation. To define avoid area.

  • exclude (Optional[List[str]]) – A comma separated list of three-letter country codes (ISO-3166-1 alpha-3 code) that routes will exclude.

Returns

RoutingResponse object.

Return type

here_location_services.responses.RoutingResponse

matrix(origins, region_definition, async_req=False, destinations=None, profile=None, departure_time=None, routing_mode=None, transport_mode=None, avoid_features=None, avoid_areas=None, truck=None, matrix_attributes=None)[source]

Calculate routing matrix between multiple origins and destinations using synchronous and asynchronous requests.

A routing matrix is a matrix with rows labeled by origins and columns by destinations. Each entry of the matrix is travel time or distance from the origin to the destination. The response contains 2 optional flat arrays TravelTimes and distances depending upon the specified matrix_attributes. Each array represents a 2D matrix where rows (i) corresponds to origins and columns (j) to destinations. The kth position in the array corresponds to the (i, j) position in the matrix defined by the following relationship: k = num_destitions * i + j.

Parameters
Raises

  • ValueError – If conflicting options are provided.

  • ApiError – If API response status code is not as expected.

Returns

MatrixRoutingResponse object.

Return type

here_location_services.responses.MatrixRoutingResponse