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