A Python client for Mapbox web services
- Geocoding
- Forward (place names ⇢ longitude, latitude)
- Reverse (longitude, latitude ⇢ place names)
- Upload
- Upload data to be processed and hosted by Mapbox.
- Other services coming soon
$ pip install mapboxTo 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.
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.
The mapbox module includes a CLI program named mbx.
$ mbx --help
Usage: mbx [OPTIONS] COMMAND [ARGS]...
This is the command line interface to Mapbox web services.
Mapbox web services require an access token. Your token is shown on the
https://www.mapbox.com/developers/api/ page when you are logged in. The
token can be provided on the command line
$ mbx --access-token MY_TOKEN ...
or as an environment variable named MAPBOX_ACCESS_TOKEN or
MapboxAccessToken.
$ export MAPBOX_ACCESS_TOKEN=MY_TOKEN
$ mbx ...
Options:
--access-token TEXT Your Mapbox access token.
-v, --verbose Increase verbosity.
--version Show the version and exit.
-q, --quiet Decrease verbosity.
--help Show this message and exit.
Commands:
geocode Geocode an address or coordinates.The mbx-geocode command can do forward or reverse geocoding.
$ mbx geocode --help
Usage: mbx geocode [OPTIONS] [QUERY]
This command returns places matching an address (forward mode) or places
matching coordinates (reverse mode).
In forward (the default) mode the query argument shall be an address such
as '1600 pennsylvania ave nw'.
$ mbx geocode '1600 pennsylvania ave nw'
In reverse mode the query argument shall be a JSON encoded array of
longitude and latitude (in that order) in decimal degrees.
$ mbx geocode --reverse '[-77.4371, 37.5227]'
An access token is required, see `mbx --help`.
Options:
--forward / --reverse Perform a forward or reverse geocode. [default:
forward]
-i, --include Include HTTP headers in the output.
--lat FLOAT Bias results toward this latitude (decimal degrees).
--lon is also required.
--lon FLOAT Bias results toward this longitude (decimal degrees).
--lat is also required.
-t, --place-type NAME Restrict results to one or more of these place types:
['address', 'country', 'place', 'poi', 'postcode',
'region'].
-o, --output TEXT Save output to a file.
--help Show this message and exit.Its output can be piped to geojsonio using geojsonio-cli.
$ mbx geocode 'Chester, NJ' | geojsoniopip install -e .[test]
py.test