mapbox 0.3.1

A Python client for Mapbox services

A Python client for Mapbox web services

The Mapbox Python SDK is a low-level client API, not a Resource API such as the ones in boto3 or github3.py. Its methods return objects containing HTTP responses from the Mapbox API.

Services

• Directions

  • Profiles for driving, walking, and cycling

  • GeoJSON & Polyline formatting

  • Instructions as text or HTML

• Distance

  • Travel-time tables between up to 100 points

  • Profiles for driving, walking and cycling

• Geocoding

  • Forward (place names ⇢ longitude, latitude)

  • Reverse (longitude, latitude ⇢ place names)

• Surface

  • Interpolates values along lines. Useful for elevation traces.

• Uploads

  • Upload data to be processed and hosted by Mapbox.

Other services coming soon.

Installation

$ pip install mapbox

API Usage

Geocoder

To begin geocoding, import the mapbox module and create a new Geocoder object with your Mapbox access token.

import mapbox

geocoder = mapbox.Geocoder(access_token='YOUR_ACCESS_TOKEN')

Geocoder’s methods return Requests style response objects.

response = geocoder.forward('Chester, NJ')

# response.json() returns the geocoding result as GeoJSON.
# response.status_code returns the HTTP API status code.

response = geocoder.reverse(lon=-74.7083, lat=40.7851)

See import mapbox; help(mapbox.Geocoder) for more detailed usage.

Upload

To upload data, you must created a token with uploads:* scopes at https://www.mapbox.com/account/apps/. Then upload any supported file to your account using the Uploader

from mapbox import Uploader
conxn = Uploader('username', access_token='MY_TOKEN')
resp = conxn.upload('RGB.byte.tif', 'RGB-byte-tif')
upload_id = resp.json()['id']

resp = conxn.status(upload_id).json()
resp['complete']  # True
resp['tileset']   # "username.RGB-byte-tif"

See import mapbox; help(mapbox.Uploader) for more detailed usage.

Directions

To get travel directions between waypoints, you can use the Directions API to route up to 25 points. Each of your input waypoints will be visited in order and should be represented by a GeoJSON point feature.

from mapbox import Directions
resp = Directions('mapbox.driving').directions([origin, destination])
driving_routes = resp.geojson()
first_route = driving_routes['features'][0]

See import mapbox; help(mapbox.Directions) for more detailed usage.

Distance

If you need to optimize travel between several waypoints, you can use the Distance API to create a “Distance Matrix” showing travel times between all waypoints. Each of your input waypoints should be a GeoJSON point feature.

from mapbox import Distance
resp = Distance('mapbox.driving').distance(points['features'])
resp.json()

which returns:

{
  "durations": [
    [ 0,    2910, null ],
    [ 2903, 0,    5839 ],
    [ 4695, 5745, 0    ]
  ]
}

See import mapbox; help(mapbox.Distance) for more detailed usage.

Surface

To query vector tile attributes along a series of points or a line, you can use the Surface API. For example, you could create an elevation profile against a GeoJSON LineString feature

from mapbox import Surface
Surface().surface([route], mapid='mapbox.mapbox-terrain-v1',
                  layer='contour', fields=['ele'])
profile_pts = resp.geojson()

See import mapbox; help(mapbox.Surface) for more detailed usage.

Testing

pip install -e .[test]
py.test

See Also

• Command line interface: https://github.com/mapbox/mapbox-cli-py

• Javascript SDK: https://github.com/mapbox/mapbox-sdk-js