Graphh’s documentation¶
Graphh is a Python module designed to make GraphHopper API queries easy.
Installation¶
To install graphh you can use pypi:
pip install graphh
and next in python:
from graphh import GraphHopper
API reference¶
-
class
graphh.
GraphHopper
(api_key, premium=False)[source]¶ GraphHopper API class.
Parameters: - api_key (str) – API key to be used for queries
- premium (bool) – Whether the account corresponding to this key is a premium account or not
Examples
>>> from graphh import GraphHopper >>> gh_client = GraphHopper(api_key=YOUR_API_KEY) >>> gh_client.address_to_latlong("Rennes, République") (48.1098593, -1.6787526) >>> latlong_Paris = gh_client.address_to_latlong("Paris, France") >>> latlong_Madrid = gh_client.address_to_latlong("Madrid, Spain") >>> gh_client.distance([latlong_Paris, latlong_Madrid], unit="km") 1269.9657 >>> gh_client.duration([latlong_Paris, latlong_Madrid], unit="h") 11.641364444444443 >>> import pprint >>> pprint.pprint(gh_client.route([latlong_Paris, latlong_Madrid])) {'hints': {'visited_nodes.average': '947.0', 'visited_nodes.sum': '947'}, 'info': {'copyrights': ['GraphHopper', 'OpenStreetMap contributors'], 'took': 43}, 'paths': [{'ascend': 11624.469142794609, 'bbox': [-3.778313, 40.412748, 2.346683, 48.878851], 'descend': 11026.474138140678, 'details': {}, 'distance': 1269965.7, 'instructions': [{'distance': 246.715, 'heading': 165.02, 'interval': [0, 2], 'sign': 0, 'street_name': 'Rue Blanche', 'text': 'Continue onto Rue Blanche', 'time': 67674}, ...
-
address_to_latlong
(address)[source]¶ This function is a simplified version of the geocoding function.
Parameters: address (str) – The address of the location that needs to be transformed. Returns: A tuple corresponding to the geographic coordinates of the location. The first element is the latitude and the second one is the longitude. Return type: tuple
-
distance
(l_latlong, unit='m')[source]¶ - This function gives the distance between precised points for a given
- itinerary
Parameters: - l_latlong (list) – The list of the tuples (latitude, longitude) of the considerated points
- unit (str) – The unit of the distance returned chosen between “m” and “km” By default the unit will be in meters
Returns: The number of the distance for the itinerary for the unit chosen
Return type: float
-
duration
(l_latlong, vehicle='car', unit='ms')[source]¶ - This function give the time between precised points for a given
- itinerary
Parameters: - l_latlong (list) – The list of the tuples (latitude, longitude) of the considerated points
- vehicle (str) – The type of vehicle chosen in the list : [“car”, “foot”, “bike”] if the acount is not premium And can be chosen in the list : [“small_truck”, “truck”, “scooter”, “hike”, “mtb”, “racingbike”] if it is By default the vehicle will be car
- unit (str) – The unit of the duration returned chosen between “ms”, “s”, “min” and “h” By default the unit will be milliseconds
Returns: The number of the time for the itinerary for the unit and vehicle chosen
Return type: float
-
elevation_point
(latlong)[source]¶ This function give an elevation for a given geographic coordinates
Parameters: latlong (tuple) – The geographic coordinates that need to be transformed. The first element is the latitude and the second one is the longitude. Returns: Elevation of one geographic coordinate couple Return type: float
-
geocode
(address, limit=1, locale='en')[source]¶ This function does geocoding. It transforms a given address into matching geographic coordinates.
Parameters: - address (str) – The address of the location that needs to be transformed.
- limit (int, optional) – The number of matching location you would like to get. By default, the function will only return one location.
- locale (str, optional) – The language of the answer. By default, the answer will be in english.
Returns: A dictionary containing the matching locations’ information, including their geographic coordinates, and the number of ms it took.
Return type: dict
-
latlong_to_address
(latlong)[source]¶ - This function is a simplified version of the reverse geocoding
- function.
Parameters: latlong (tuple) – The geographic coordinates that need to be transformed. The first element is the latitude and the second one is the longitude. Returns: The address of the location. Return type: str
-
matrix
(l_from_address, l_to_address, out_array, format='default', vehicle='car', request='get')[source]¶ This function gives one matrix between the points: distances, times or weights
Parameters: - l_from_address (list) – The list containing the cities, address of the points
- l_to_address (list) – The list containing the cities, address of the points
- out_array (str) – Specifies which array should be included in the response from the list [“distances”, “times”, “weights”] The units of the entries of distances are meters, of times are seconds and of weights is arbitrary and it can differ for different vehicles or versions of this API
- format (str, optional) – Specifies how the array should be drawn from the list [“pandas”,”numpy”,”default”] By default, the array is values “default”
- vehicle (str, optional) – The type of vehicle chosen in the list : [“car”, “foot”, “bike”] if the acount is not premium And can be chosen in the list : [“small_truck”, “truck”, “scooter”, “hike”, “mtb”, “racingbike”] if it is
- request (str, optional) – Type of request : GET or POST By default, the request will be GET
Returns: - dataframe : data frame
A data frame with for names columns the address for l_to_address and names rows the address for l_from_address and data of matrix
- matrix : array
A array data of the function matrix
- list : list
A list of data list of the function matrix
Return type: 3 possibilities
-
matrix_numpy
(dic, out_array)[source]¶ This function gives a matrix (numpy) between the points: distances, times or weights
Parameters: - dic (dictionary) – A dictionary containing distances, times and weights matrices
- out_array (str) – Specifies which array should be included in the response from the list [“distances”, “times”, “weights”] The units of the entries of distances are meters, of times are seconds and of weights is arbitrary and it can differ for different vehicles or versions of this API
Returns: dataframe – A data frame with for names columns the address for l_to_address and names rows the address for l_from_address and data of matrix
Return type: data frame
-
matrix_pandas
(dic, out_array, l_from_address, l_to_address)[source]¶ This function gives a dataframe between the points: distances, times or weights
Parameters: - dic (dictionary) – A dictionary containing distances, times and weights matrices
- out_array (str) – Specifies which array should be included in the response from the list [“distances”, “times”, “weights”] The units of the entries of distances are meters, of times are seconds and of weights is arbitrary and it can differ for different vehicles or versions of this API
- l_from_address (list) – The list containing the cities, address of the points
- l_to_address (list) – The list containing the cities, address of the points
Returns: dataframe – A data frame with for names columns the address for l_to_address and names rows the address for l_from_address and data of matrix
Return type: data frame
-
matrix_request
(l_from_points, l_to_points, request='get', vehicle='car')[source]¶ - This function gives the different possible matrix
- between the points: distance, temp, weight
Parameters: - l_from_points (list) – Tuple list (latitude, longitude) of the starting points for the routes
- l_to_points (list) – Tuple list (latitude, longitude) of the destination points for the routes
- request (str, optional) – Type of request : GET or POST By default, the request will be GET
- vehicle (str, optional) – The type of vehicle chosen in the list : [“car”, “foot”, “bike”] if the acount is not premium And can be chosen in the list : [“small_truck”, “truck”, “scooter”, “hike”, “mtb”, “racingbike”] if it is
Returns: A dictionary containing distances, times and weights matrices
Return type: dict
-
reverse_geocode
(latlong, locale='en')[source]¶ - This function does reverse geocoding.
- It transforms given geographic coordinates into matching addresses.
Parameters: - latlong (tuple) – The geographic coordinates that need to be transformed. The first element is the latitude and the second one is the longitude.
- locale (str, optional) – The language of the answer. By default, the answer will be in english.
Returns: A dictionary containing the matching locations’ information, including their addresses, and the number of ms it took.
Return type: dict
-
route
(l_latlong, request='get', vehicle='car', locale='en', calc_points='true', instructions='true', points_encoded='true', elevation='false')[source]¶ This function give an itinerary between given points
Parameters: - l_latlong (list) – Tuple list (latitude, longitude) of the considered points
- request (str, optional) – Type of request : GET or POST By default, the request will be GET
- vehicle (str, optional) – The type of vehicle chosen in the list : [“car”, “foot”, “bike”] if the account is not premium And can be chosen in the list : [“small_truck”, “truck”, “scooter”, “hike”, “mtb”, “racingbike”] if it is
- locale (str, optional) – The language of the answer. By default, the answer will be in english.
- calc_points (boolean, optional) – If the points for the route should be calculated at all. default = true
- instructions (boolean, optional) – If instructions should be calculated and returned default = true
- points_encoded (boolean, optional) – If false, the coordinates in point and snapped_waypoints are returned as lists of positions using the order [lon,lat,elevation]. If true, the coordinates will be encoded as a string. default = true
- elevation (boolean, optional) – If true, a third coordinate, the altitude, is included to all positions in the response
Returns: A dictionary of the matching itinerary containing distance, time, ascend, descend, points (encoded or not), instructions with street name and description what the user has to do in order to follow the route.
Return type: dict