Pure Python implementation of clients for Mapbox services

2017-12-27 13:43:14 +01:00
parent b16f7e6ed5
commit 8c0af7d51d
13 changed files with 620 additions and 1 deletions
@@ -0,0 +1,5 @@
+from routing import MapboxRouting, MapboxRoutingResponse
+from geocoder import MapboxGeocoder
+from isolines import MapboxIsolines
+from matrix_client import MapboxMatrixClient
+from exceptions import ServiceException
@@ -0,0 +1,18 @@
+'''
+Exceptions for the Mapbox services Python wrapper.
+'''
+
+
+class ServiceException(Exception):
+    '''
+    Exception to be raised if any Service problem is found.
+    '''
+
+    def __init__(self, code, message):
+        self.code = code
+        self.message = message
+
+    def __str__(self):
+        return repr('ServiceException ({code}): {message}'.format(
+            code=self.code,
+            message=self.message))
@@ -0,0 +1,59 @@
+'''
+Python client for the Mapbox Geocoder service.
+'''
+
+import json
+import requests
+from mapbox import Geocoder
+from cartodb_services.metrics import Traceable
+from cartodb_services.mapbox.exceptions import ServiceException
+
+ACCESS_TOKEN = 'pk.eyJ1IjoiYWNhcmxvbiIsImEiOiJjamJuZjQ1Zjc0Ymt4Mnh0YmFrMmhtYnY4In0.gt9cw0VeKc3rM2mV5pcEmg'
+
+EPHEMERAL_GEOCODER = 'mapbox.places'
+PERMANENT_GEOCODER = 'mapbox.places-permanent'
+DEFAULT_GEOCODER = EPHEMERAL_GEOCODER
+
+ENTRY_FEATURES = 'features'
+ENTRY_CENTER = 'center'
+ENTRY_GEOMETRY = 'geometry'
+ENTRY_COORDINATES = 'coordinates'
+ENTRY_TYPE = 'type'
+TYPE_POINT = 'Point'
+
+
+class MapboxGeocoder(Traceable):
+    '''
+    Python wrapper for the Mapbox Geocoder service.
+    '''
+
+    def __init__(self, token=ACCESS_TOKEN, name=DEFAULT_GEOCODER):
+        self._token = token
+        self._geocoder = Geocoder(access_token=self._token, name=name)
+
+    def _parse_geocoder_response(self, response):
+        json_response = json.loads(response)
+        feature = json_response[ENTRY_FEATURES][0]
+
+        return self._extract_lng_lat_from_feature(feature)
+
+    def _extract_lng_lat_from_feature(self, feature):
+        geometry = feature[ENTRY_GEOMETRY]
+        if geometry[ENTRY_TYPE] == TYPE_POINT:
+            location = geometry[ENTRY_COORDINATES]
+        else:
+            location = feature[ENTRY_CENTER]
+
+        longitude = location[0]
+        latitude = location[1]
+        return [longitude, latitude]
+
+    def geocode(self, address, country=None):
+        response = self._geocoder.forward(address=address,
+                                          country=country,
+                                          limit=1)
+
+        if response.status_code == requests.codes.ok:
+            return self._parse_geocoder_response(response.text)
+        else:
+            raise ServiceException(response.status_code, response.content)
@@ -0,0 +1,146 @@
+'''
+Python implementation for Mapbox services based isolines.
+Uses the Mapbox Time Matrix service.
+'''
+
+import json
+from cartodb_services.tools.spherical import (get_angles,
+                                              calculate_dest_location)
+from cartodb_services.mapbox.matrix_client import (validate_profile,
+                                                   DEFAULT_PROFILE,
+                                                   PROFILE_WALKING,
+                                                   PROFILE_DRIVING,
+                                                   PROFILE_CYCLING,
+                                                   ENTRY_DURATIONS)
+
+MAX_SPEEDS = {
+    PROFILE_WALKING: 3.3333333,  # In m/s, assuming 12km/h walking speed
+    PROFILE_CYCLING: 16.67,  # In m/s, assuming 60km/h max speed
+    PROFILE_DRIVING: 41.67  # In m/s, assuming 140km/h max speed
+}
+
+DEFAULT_NUM_ANGLES = 24
+DEFAULT_MAX_ITERS = 5
+DEFAULT_TOLERANCE = 0.1
+
+MATRIX_NUM_ANGLES = DEFAULT_NUM_ANGLES
+MATRIX_MAX_ITERS = DEFAULT_MAX_ITERS
+MATRIX_TOLERANCE = DEFAULT_TOLERANCE
+
+UNIT_FACTOR_ISOCHRONE = 1.0
+UNIT_FACTOR_ISODISTANCE = 1000.0
+DEFAULT_UNIT_FACTOR = UNIT_FACTOR_ISOCHRONE
+
+
+class MapboxIsolines():
+    '''
+    Python wrapper for Mapbox services based isolines.
+    '''
+
+    def __init__(self, matrix_client, routing_client):
+        self._matrix_client = matrix_client
+        self._routing_client = routing_client
+
+    def _calculate_matrix_cost(self, origin, targets, isorange,
+                               profile=DEFAULT_PROFILE,
+                               unit_factor=UNIT_FACTOR_ISOCHRONE,
+                               number_of_angles=MATRIX_NUM_ANGLES):
+        response = self._matrix_client.matrix([origin] + targets,
+                                              profile)
+        json_response = json.loads(response)
+
+        costs = [None] * number_of_angles
+
+        for idx, cost in enumerate(json_response[ENTRY_DURATIONS][0][1:]):
+            if cost:
+                costs[idx] = cost * unit_factor
+            else:
+                costs[idx] = isorange
+
+        return costs
+
+    def calculate_isochrone(self, origin, time_range,
+                            profile=DEFAULT_PROFILE):
+        validate_profile(profile)
+
+        max_speed = MAX_SPEEDS[profile]
+        upper_rmax = max_speed * time_range  # an upper bound for the radius
+
+        return self.calculate_isoline(origin=origin,
+                                      isorange=time_range,
+                                      upper_rmax=upper_rmax,
+                                      cost_method=self._calculate_matrix_cost,
+                                      profile=profile,
+                                      unit_factor=UNIT_FACTOR_ISOCHRONE,
+                                      number_of_angles=MATRIX_NUM_ANGLES,
+                                      max_iterations=MATRIX_MAX_ITERS,
+                                      tolerance=MATRIX_TOLERANCE)
+
+    def calculate_isodistance(self, origin, distance_range,
+                              profile=DEFAULT_PROFILE):
+        validate_profile(profile)
+
+        max_speed = MAX_SPEEDS[profile]
+        time_range = distance_range / max_speed
+
+        return self.calculate_isochrone(origin=origin,
+                                        time_range=time_range,
+                                        profile=profile)
+
+    def calculate_isoline(self, origin, isorange, upper_rmax,
+                          cost_method=_calculate_matrix_cost,
+                          profile=DEFAULT_PROFILE,
+                          unit_factor=DEFAULT_UNIT_FACTOR,
+                          number_of_angles=DEFAULT_NUM_ANGLES,
+                          max_iterations=DEFAULT_MAX_ITERS,
+                          tolerance=DEFAULT_TOLERANCE):
+        # Formally, a solution is an array of {angle, radius, lat, lon, cost}
+        # with cardinality number_of_angles
+        # we're looking for a solution in which
+        # abs(cost - isorange) / isorange <= TOLERANCE
+
+        # Initial setup
+        angles = get_angles(number_of_angles)
+        rmax = [upper_rmax] * number_of_angles
+        rmin = [0.0] * number_of_angles
+        location_estimates = [calculate_dest_location(origin, a,
+                                                      upper_rmax / 2.0)
+                              for a in angles]
+
+        # Iterate to refine the first solution
+        for i in xrange(0, max_iterations):
+            # Calculate the "actual" cost for each location estimate.
+            # NOTE: sometimes it cannot calculate the cost and returns None.
+            #   Just assume isorange and stop the calculations there
+
+            costs = cost_method(origin=origin, targets=location_estimates,
+                                isorange=isorange, profile=profile,
+                                unit_factor=unit_factor,
+                                number_of_angles=number_of_angles)
+
+            errors = [(cost - isorange) / float(isorange) for cost in costs]
+            max_abs_error = max([abs(e) for e in errors])
+            if max_abs_error <= tolerance:
+                # good enough, stop there
+                break
+
+            # let's refine the solution, binary search
+            for j in xrange(0, number_of_angles):
+
+                if abs(errors[j]) > tolerance:
+                    if errors[j] > 0:
+                        rmax[j] = (rmax[j] + rmin[j]) / 2.0
+                    else:
+                        rmin[j] = (rmax[j] + rmin[j]) / 2.0
+
+                    location_estimates[j] = calculate_dest_location(origin,
+                                                                    angles[j],
+                                                                    (rmax[j] + rmin[j]) / 2.0)
+
+        # delete points that got None
+        location_estimates_filtered = []
+        for i, c in enumerate(costs):
+            if c != isorange:
+                location_estimates_filtered.append(location_estimates[i])
+
+        return location_estimates_filtered
@@ -0,0 +1,73 @@
+'''
+Python client for the Mapbox Time Matrix service.
+'''
+
+import requests
+from cartodb_services.metrics import Traceable
+from cartodb_services.tools.coordinates import (validate_coordinates,
+                                                marshall_coordinates)
+from exceptions import ServiceException
+
+ACCESS_TOKEN = 'pk.eyJ1IjoiYWNhcmxvbiIsImEiOiJjamJuZjQ1Zjc0Ymt4Mnh0YmFrMmhtYnY4In0.gt9cw0VeKc3rM2mV5pcEmg'
+
+BASEURI = ('https://api.mapbox.com/directions-matrix/v1/mapbox/{profile}/'
+           '{coordinates}'
+           '?access_token={token}'
+           '&sources=0'  # Set the first coordinate as source...
+           '&destinations=all')  # ...and the rest as destinations
+
+NUM_COORDINATES_MIN = 2  # https://www.mapbox.com/api-documentation/#matrix
+NUM_COORDINATES_MAX = 25  # https://www.mapbox.com/api-documentation/#matrix
+
+PROFILE_DRIVING_TRAFFIC = 'driving-traffic'
+PROFILE_DRIVING = 'driving'
+PROFILE_CYCLING = 'cycling'
+PROFILE_WALKING = 'walking'
+DEFAULT_PROFILE = PROFILE_DRIVING
+
+VALID_PROFILES = [PROFILE_DRIVING_TRAFFIC,
+                  PROFILE_DRIVING,
+                  PROFILE_CYCLING,
+                  PROFILE_WALKING]
+
+ENTRY_DURATIONS = 'durations'
+
+
+def validate_profile(profile):
+    if profile not in VALID_PROFILES:
+        raise ValueError('{profile} is not a valid profile. '
+                         'Valid profiles are: {valid_profiles}'.format(
+                             profile=profile,
+                             valid_profiles=', '.join(
+                                 [x for x in VALID_PROFILES])))
+
+
+class MapboxMatrixClient(Traceable):
+    '''
+    Python wrapper for the Mapbox Time Matrix service.
+    '''
+
+    def __init__(self, token=ACCESS_TOKEN):
+        self.token = token
+
+    def _uri(self, coordinates, profile=DEFAULT_PROFILE):
+        return BASEURI.format(profile=profile, coordinates=coordinates,
+                              token=self.token)
+
+    def _parse_matrix_response(self, response):
+        return response
+
+    def matrix(self, coordinates, profile=DEFAULT_PROFILE):
+        validate_profile(profile)
+        validate_coordinates(coordinates,
+                             NUM_COORDINATES_MIN, NUM_COORDINATES_MAX)
+
+        coords = marshall_coordinates(coordinates)
+
+        uri = self._uri(coords, profile)
+        response = requests.get(uri)
+
+        if response.status_code == requests.codes.ok:
+            return self._parse_matrix_response(response.text)
+        else:
+            raise ServiceException(response.status_code, response.content)
@@ -0,0 +1,107 @@
+'''
+Python client for the Mapbox Routing service.
+'''
+
+import json
+import requests
+from cartodb_services.metrics import Traceable
+from cartodb_services.tools import PolyLine
+from cartodb_services.tools.coordinates import (validate_coordinates,
+                                                marshall_coordinates)
+from cartodb_services.mapbox.exceptions import ServiceException
+
+ACCESS_TOKEN = 'pk.eyJ1IjoiYWNhcmxvbiIsImEiOiJjamJuZjQ1Zjc0Ymt4Mnh0YmFrMmhtYnY4In0.gt9cw0VeKc3rM2mV5pcEmg'
+
+BASEURI = ('https://api.mapbox.com/directions/v5/mapbox/{profile}/'
+           '{coordinates}'
+           '?access_token={token}'
+           '&overview={overview}')
+
+NUM_WAYPOINTS_MIN = 2  # https://www.mapbox.com/api-documentation/#directions
+NUM_WAYPOINTS_MAX = 25  # https://www.mapbox.com/api-documentation/#directions
+
+PROFILE_DRIVING_TRAFFIC = 'driving-traffic'
+PROFILE_DRIVING = 'driving'
+PROFILE_CYCLING = 'cycling'
+PROFILE_WALKING = 'walking'
+DEFAULT_PROFILE = PROFILE_DRIVING
+
+DEFAULT_OVERVIEW = 'full'
+
+VALID_PROFILES = [PROFILE_DRIVING_TRAFFIC,
+                  PROFILE_DRIVING,
+                  PROFILE_CYCLING,
+                  PROFILE_WALKING]
+
+ENTRY_ROUTES = 'routes'
+ENTRY_GEOMETRY = 'geometry'
+ENTRY_DURATION = 'duration'
+ENTRY_DISTANCE = 'distance'
+
+
+class MapboxRouting(Traceable):
+    '''
+    Python wrapper for the Mapbox Routing service.
+    '''
+
+    def __init__(self, token=ACCESS_TOKEN):
+        self._token = token
+
+    def _uri(self, coordinates, profile=DEFAULT_PROFILE,
+             overview=DEFAULT_OVERVIEW):
+        return BASEURI.format(profile=profile, coordinates=coordinates,
+                              token=self._token, overview=overview)
+
+    def _validate_profile(self, profile):
+        if profile not in VALID_PROFILES:
+            raise ValueError('{profile} is not a valid profile. '
+                             'Valid profiles are: {valid_profiles}'.format(
+                                 profile=profile,
+                                 valid_profiles=', '.join(
+                                     [x for x in VALID_PROFILES])))
+
+    def _parse_routing_response(self, response):
+        json_response = json.loads(response)
+        route = json_response[ENTRY_ROUTES][0]  # Force the first route
+
+        geometry = PolyLine().decode(route[ENTRY_GEOMETRY])
+        distance = route[ENTRY_DISTANCE]
+        duration = route[ENTRY_DURATION]
+
+        return MapboxRoutingResponse(geometry, distance, duration)
+
+    def directions(self, waypoints, profile=DEFAULT_PROFILE):
+        self._validate_profile(profile)
+        validate_coordinates(waypoints, NUM_WAYPOINTS_MIN, NUM_WAYPOINTS_MAX)
+
+        coordinates = marshall_coordinates(waypoints)
+
+        uri = self._uri(coordinates, profile)
+        response = requests.get(uri)
+
+        if response.status_code == requests.codes.ok:
+            return self._parse_routing_response(response.text)
+        elif response.status_code == requests.codes.bad_request:
+            return MapboxRoutingResponse(None, None, None)
+        else:
+            raise ServiceException(response.status_code, response.content)
+
+
+class MapboxRoutingResponse:
+
+    def __init__(self, shape, length, duration):
+        self._shape = shape
+        self._length = length
+        self._duration = duration
+
+    @property
+    def shape(self):
+        return self._shape
+
+    @property
+    def length(self):
+        return self._length
+
+    @property
+    def duration(self):
+        return self._duration