Add an icon to a sprite.
Parameters
styleid
string the id for an existing styleiconName
string icon's nameicon
Buffer icon content as a buffercallback
Function called with (err)
Examples
var MapboxClient = require('mapbox');
var fs = require('fs');
var client = new MapboxClient('ACCESSTOKEN');
client.addIcon('style-id', 'icon-name', fs.readFileSync('icon.png'), function(err) {
if (!err) console.log('added icon!');
});
Returns Promise response
Create a style, given the style as a JSON object.
Parameters
style
Object Mapbox GL Style Spec objectcallback
Function called with (err, createdStyle)
Examples
var MapboxClient = require('mapbox');
var client = new MapboxClient('ACCESSTOKEN');
var style = {
'version': 8,
'name': 'My Awesome Style',
'metadata': {},
'sources': {},
'layers': [],
'glyphs': 'mapbox://fonts/{owner}/{fontstack}/{range}.pbf'
};
client.createStyle(style, function(err, createdStyle) {
console.log(createdStyle);
});
Returns Promise response
Delete an icon from a sprite.
Parameters
styleid
string the id for an existing styleiconName
string icon's namecallback
Function called with (err)
Examples
var MapboxClient = require('mapbox');
var client = new MapboxClient('ACCESSTOKEN');
client.deleteIcon('style-id', 'icon-name', function(err) {
if (!err) console.log('deleted icon!');
});
Returns Promise response
Deletes a particular style.
Parameters
styleid
string the id for an existing stylecallback
Function called with (err)
Examples
var MapboxClient = require('mapbox');
var client = new MapboxClient('ACCESSTOKEN');
client.deleteStyle('style-id', function(err) {
if (!err) console.log('deleted!');
});
Returns Promise a promise with the response
Embed a style.
Parameters
styleid
string the id for an existing styleoptions
Object optional paramsoptions.title
[boolean] If true, shows a title box in upper right corner with map title and owner (optional, defaultfalse
)options.zoomwheel
[boolean] Disables zooming with mouse scroll wheel (optional, defaulttrue
)
Examples
var MapboxClient = require('mapbox');
var client = new MapboxClient('ACCESSTOKEN');
var url = client.embedStyle('style-id');
Returns string URL of style embed page
To retrieve a listing of styles for a particular account.
Parameters
callback
Function called with (err, styles)
Examples
var MapboxClient = require('mapbox');
var client = new MapboxClient('ACCESSTOKEN');
client.listStyles(function(err, styles) {
console.log(styles);
// [{ version: 8,
// name: 'Light',
// center: [ -77.0469979435026, 38.898634927602814 ],
// zoom: 12.511766533145998,
// bearing: 0,
// pitch: 0,
// created: '2016-02-09T14:26:15.059Z',
// id: 'STYLEID',
// modified: '2016-02-09T14:28:31.253Z',
// owner: '{username}' },
// { version: 8,
// name: 'Dark',
// created: '2015-08-28T18:05:22.517Z',
// id: 'STYILEID',
// modified: '2015-08-28T18:05:22.517Z',
// owner: '{username}' }]
});
Returns Promise response
Get font glyph ranges
Parameters
font
string or fontsstart
number character code of starting glyphend
number character code of last glyph. typically the same as start + 255callback
Function called with (err)
Examples
var MapboxClient = require('mapbox');
var client = new MapboxClient('ACCESSTOKEN');
client.readFontGlyphRanges('Arial Unicode', 0, 255, function(err, ranges) {
if (!err) console.log(ranges);
});
Returns Promise response
Read sprite
Parameters
styleid
string the id for an existing styleoptions
[Object] optional optionsoptions.retina
boolean whether the sprite JSON should be for a retina sprite.
callback
Function called with (err)
Examples
var MapboxClient = require('mapbox');
var client = new MapboxClient('ACCESSTOKEN');
client.readSprite('style-id', {
retina: true
}, function(err) {
if (!err) console.log('deleted!');
});
Returns Promise response
Reads a particular style.
Parameters
styleid
string the id for an existing stylecallback
Function called with (err, style)
Examples
var MapboxClient = require('mapbox');
var client = new MapboxClient('ACCESSTOKEN');
client.readStyle('style-id', function(err, style) {
if (!err) console.log(style);
});
Returns Promise response
Update a style, given the style as a JSON object.
Parameters
style
Object Mapbox GL Style Spec objectstyleid
string style idcallback
Function called with (err, createdStyle)
Examples
var MapboxClient = require('mapbox');
var client = new MapboxClient('ACCESSTOKEN');
var style = {
'version': 8,
'name': 'My Awesome Style',
'metadata': {},
'sources': {},
'layers': [],
'glyphs': 'mapbox://fonts/{owner}/{fontstack}/{range}.pbf'
};
client.updateStyle(style, 'style-id', function(err, createdStyle) {
console.log(createdStyle);
});
Returns Promise response
To create a new dataset. Valid properties include title and description (not required). This request requires an access token with the datasets:write scope.
Parameters
options
[object] an object defining a dataset's propertiesoptions.name
[string] the dataset's nameoptions.description
[string] the dataset's description
callback
Function called with (err, dataset)
Examples
var MapboxClient = require('mapbox');
var client = new MapboxClient('ACCESSTOKEN');
client.createDataset({ name: 'foo', description: 'bar' }, function(err, dataset) {
console.log(dataset);
// {
// "owner": {account},
// "id": {dataset id},
// "name": "foo",
// "description": "description",
// "created": {timestamp},
// "modified": {timestamp}
// }
});
Returns Promise response
To delete a particular dataset. This request requires an access token with the datasets:write scope.
Parameters
dataset
string the id for an existing datasetcallback
Function called with (err)
Examples
var MapboxClient = require('mapbox');
var client = new MapboxClient('ACCESSTOKEN');
client.deleteDataset('dataset-id', function(err) {
if (!err) console.log('deleted!');
});
Returns Promise response
Delete an existing feature from a dataset. This request requires an access token with the datasets:write scope.
Parameters
id
string theid
of the feature to readdataset
string the id for an existing datasetcallback
Function called with (err)
Examples
var MapboxClient = require('mapbox');
var client = new MapboxClient('ACCESSTOKEN');
client.deleteFeature('feature-id', 'dataset-id', function(err, feature) {
if (!err) console.log('deleted!');
});
Returns Promise response
Insert a feature into a dataset. This can be a new feature, or overwrite an existing one.
If overwriting an existing feature, make sure that the feature's id
property correctly identifies
the feature you wish to overwrite.
For new features, specifying an id
is optional. If you do not specify an id
, one will be assigned
and returned as part of the response.
This request requires an access token with the datasets:write scope.
There are a number of limits to consider when making this request:
- a single feature cannot be larger than 500 KB
- the dataset must not exceed 2000 total features
- the dataset must not exceed a total of 5 MB
Parameters
feature
object the feature to insert. Must be a valid GeoJSON feature per http://geojson.org/geojson-spec.html#feature-objectsdataset
string the id for an existing datasetcallback
Function called with (err, feature)
Examples
// Insert a brand new feature without an id
var MapboxClient = require('mapbox');
var client = new MapboxClient('ACCESSTOKEN');
var feature = {
"type": "Feature",
"properties": {
"name": "Null Island"
},
"geometry": {
"type": "Point",
"coordinates": [0, 0]
}
};
client.insertFeature(feature, 'dataset-id', function(err, feature) {
console.log(feature);
// {
// "id": {feature id},
// "type": "Feature",
// "properties": {
// "name": "Null Island"
// },
// "geometry": {
// "type": "Point",
// "coordinates": [0, 0]
// }
// }
});
// Insert a brand new feature with an id, or overwrite an existing feature at that id
var MapboxClient = require('mapbox');
var client = new MapboxClient('ACCESSTOKEN');
var feature = {
"id": "feature-id",
"type": "Feature",
"properties": {
"name": "Null Island"
},
"geometry": {
"type": "Point",
"coordinates": [0, 0]
}
};
client.insertFeature(feature, 'dataset-id', function(err, feature) {
console.log(feature);
// {
// "id": "feature-id",
// "type": "Feature",
// "properties": {
// "name": "Null Island"
// },
// "geometry": {
// "type": "Point",
// "coordinates": [0, 0]
// }
// }
});
Returns Promise response
To retrieve a listing of datasets for a particular account. This request requires an access token with the datasets:read scope.
Parameters
opts
[Object] list options (optional, default{}
)opts.limit
number limit, for pagingopts.fresh
boolean whether to request fresh data
callback
Function called with (err, datasets)
Examples
var MapboxClient = require('mapbox');
var client = new MapboxClient('ACCESSTOKEN');
client.listDatasets(function(err, datasets) {
console.log(datasets);
// [
// {
// "owner": {account},
// "id": {dataset id},
// "name": {dataset name},
// "description": {dataset description},
// "created": {timestamp},
// "modified": {timestamp}
// },
// {
// "owner": {account},
// "id": {dataset id},
// "name": {dataset name},
// "description": {dataset description},
// "created": {timestamp},
// "modified": {timestamp}
// }
// ]
});
Returns Promise response
Retrive a list of the features in a particular dataset. The response body will be a GeoJSON FeatureCollection. This request requires an access token with the datasets:read scope.
Parameters
dataset
string the id for an existing datasetoptions
[object] an object for passing pagination argumentsoptions.limit
[number] The maximum number of objects to return. This value must be between 1 and 100. The API will attempt to return the requested number of objects, but receiving fewer objects does not necessarily signal the end of the collection. Receiving an empty page of results is the only way to determine when you are at the end of a collection.
callback
Function called with (err, collection)
Examples
var MapboxClient = require('mapbox');
var client = new MapboxClient('ACCESSTOKEN');
client.listFeatures('dataset-id', options, function(err, collection) {
console.log(collection);
{
"type": "FeatureCollection",
"features": [
{
"id": {feature id},
"type": "Feature",
"properties": {feature properties}
"geometry": {feature geometry}
},
{
"id": {feature id},
"type": "Feature",
"properties": {feature properties}
"geometry": {feature geometry}
}
]
}
});
Returns Promise response
To retrieve information about a particular dataset. This request requires an access token with the datasets:read scope.
Parameters
dataset
string the id for an existing datasetcallback
Function called with (err, dataset)
Examples
var MapboxClient = require('mapbox');
var client = new MapboxClient('ACCESSTOKEN');
client.readDataset('dataset-id', function(err, dataset) {
console.log(dataset);
// {
// "owner": {account},
// "id": "dataset-id",
// "name": {dataset name},
// "description": {dataset description},
// "created": {timestamp},
// "modified": {timestamp}
// }
});
Returns Promise response
Read an existing feature from a dataset. This request requires an access token with the datasets:read scope.
Parameters
id
string theid
of the feature to readdataset
string the id for an existing datasetcallback
Function called with (err, feature)
Examples
var MapboxClient = require('mapbox');
var client = new MapboxClient('ACCESSTOKEN');
client.readFeature('feature-id', 'dataset-id', function(err, feature) {
console.log(feature);
// {
// "id": "feature-id",
// "type": "Feature",
// "properties": {
// "name": "Null Island"
// },
// "geometry": {
// "type": "Point",
// "coordinates": [0, 0]
// }
// }
});
Returns Promise response
To make updates to a particular dataset's properties. This request requires an access token with the datasets:write scope.
Parameters
dataset
string the id for an existing datasetoptions
[object] an object defining updates to the dataset's propertiesoptions.name
[string] the updated dataset's nameoptions.description
[string] the updated dataset's description
callback
Function called with (err, dataset)
Examples
var MapboxClient = require('mapbox');
var client = new MapboxClient('ACCESSTOKEN');
var options = { name: 'foo' };
client.updateDataset('dataset-id', options, function(err, dataset) {
console.log(dataset);
// {
// "owner": {account},
// "id": "dataset-id",
// "name": "foo",
// "description": {dataset description},
// "created": {timestamp},
// "modified": {timestamp}
// }
});
Returns Promise response
Create a temporary token
Parameters
expires
string Time token expires in RFC 3339scopes
Array List of scopes for the new tokencallback
[Function] called with (err, token, response)
Examples
var MapboxClient = require('mapbox');
var client = new MapboxClient('ACCESSTOKEN');
client.createToken('2016-09-15T19:27:53.000Z', ["styles:read", "fonts:read"], function(err, createdToken) {
console.log(createdToken);
});
Returns Promise response
Create a token
Parameters
note
string Note attached to the tokenscopes
Array List of scopes for the new tokencallback
[Function] called with (err, token, response)
Examples
var MapboxClient = require('mapbox');
var client = new MapboxClient('ACCESSTOKEN');
client.createToken('My top secret project', ["styles:read", "fonts:read"], function(err, createdToken) {
console.log(createdToken);
});
Returns Promise response
Delete a token's authorization
Parameters
authorization_id
string Authorization IDcallback
[Function] called with (err, token, response)
Examples
var MapboxClient = require('mapbox');
var client = new MapboxClient('ACCESSTOKEN');
client.deleteTokenAuthorization('auth id', function(err) {
});
Returns Promise response
List scopes
Parameters
callback
[Function] called with (err, scopes, response)
Examples
var MapboxClient = require('mapbox');
var client = new MapboxClient('ACCESSTOKEN');
client.listScopes(function(err, scopes) {
console.log(scopes);
});
Returns Promise response
To retrieve a listing of tokens for a particular account.
Parameters
callback
[Function] called with (err, tokens, response)
Examples
var MapboxClient = require('mapbox');
var client = new MapboxClient('ACCESSTOKEN');
client.listTokens(function(err, tokens) {
console.log(tokens);
// [{ client: 'api'
// note: 'Default Public Token',
// usage: 'pk',
// id: 'TOKENID',
// default: true,
// scopes: ['styles:tiles','styles:read','fonts:read','datasets:read'],
// created: '2016-02-09T14:26:15.059Z',
// modified: '2016-02-09T14:28:31.253Z',
// token: 'pk.TOKEN' }]
});
Returns Promise response
Retrieve a token
Parameters
access_token
string access token to checkcallback
[Function] called with (err, token, response)
Examples
var MapboxClient = require('mapbox');
var client = new MapboxClient('ACCESSTOKEN');
client.retrieveToken('ACCESSTOKEN', function(err, tokenResponse) {
console.log(tokenResponse);
});
Returns Promise response
Update a token's authorization
Parameters
authorization_id
string Authorization IDscopes
Array List of scopes for the new tokencallback
[Function] called with (err, token, response)
Examples
var MapboxClient = require('mapbox');
var client = new MapboxClient('ACCESSTOKEN');
client.updateTokenAuthorization('auth id', ["styles:read", "fonts:read"], function(err, updatedToken) {
console.log(updatedToken);
});
Returns Promise response
Create an new upload with a file previously staged on Amazon S3.
This request requires an access token with the uploads:write scope.
Parameters
options
Object an object that defines the upload's propertiesoptions.tileset
String id of the tileset to create or replace. This must consist of an account id and a unique key separated by a period. Reuse of a tileset value will overwrite existing data. To avoid overwriting existing data, you must ensure that you are using unique tileset ids.options.url
String https url of a file staged on Amazon S3.
callback
Function called with (err, upload)
Examples
var mapboxClient = new MapboxClient('ACCESSTOKEN');
// Response from a call to createUploadCredentials
var credentials = {
"accessKeyId": "{accessKeyId}",
"bucket": "somebucket",
"key": "hij456",
"secretAccessKey": "{secretAccessKey}",
"sessionToken": "{sessionToken}",
"url": "{s3 url}"
};
mapboxClient.createUpload({
tileset: [accountid, 'mytileset'].join('.'),
url: credentials.url
}, function(err, upload) {
console.log(upload);
// {
// "complete": false,
// "tileset": "example.markers",
// "error": null,
// "id": "hij456",
// "modified": "2014-11-21T19:41:10.000Z",
// "created": "2014-11-21T19:41:10.000Z",
// "owner": "example",
// "progress": 0
// }
});
Returns Promise response
Retrieve credentials that allow a new file to be staged on Amazon S3 while an upload is processed. All uploads must be staged using these credentials before being uploaded to Mapbox.
This request requires an access token with the uploads:write scope.
Parameters
callback
Function called with (err, credentials)
Examples
var mapboxClient = new MapboxClient('ACCESSTOKEN');
mapboxClient.createUploadCredentials(function(err, credentials) {
console.log(credentials);
// {
// "accessKeyId": "{accessKeyId}",
// "bucket": "somebucket",
// "key": "hij456",
// "secretAccessKey": "{secretAccessKey}",
// "sessionToken": "{sessionToken}",
// "url": "{s3 url}"
// }
// Use aws-sdk to stage the file on Amazon S3
var AWS = require('aws-sdk');
var s3 = new AWS.S3({
accessKeyId: credentials.accessKeyId,
secretAccessKey: credentials.secretAccessKey,
sessionToken: credentials.sessionToken,
region: 'us-east-1'
});
s3.putObject({
Bucket: credentials.bucket,
Key: credentials.key,
Body: fs.createReadStream('/path/to/file.mbtiles')
}, function(err, resp) {
});
});
Returns Promise response
Delete a completed upload. In-progress uploads cannot be deleted.
This request requires an access token with the uploads:delete scope.
Parameters
upload
string upload identifiercallback
Function called with (err)
Examples
var mapboxClient = new MapboxClient('ACCESSTOKEN');
mapboxClient.deleteUpload('hij456', function(err) {
});
Returns Promise response
Retrieve a listing of uploads for a particular account.
This request requires an access token with the uploads:list scope.
Parameters
callback
Function called with (err, uploads)
Examples
var mapboxClient = new MapboxClient('ACCESSTOKEN');
mapboxClient.listUploads(function(err, uploads) {
console.log(uploads);
// [
// {
// "complete": true,
// "tileset": "example.mbtiles",
// "error": null,
// "id": "abc123",
// "modified": "2014-11-21T19:41:10.000Z",
// "created": "2014-11-21T19:41:10.000Z",
// "owner": "example",
// "progress": 1
// },
// {
// "complete": false,
// "tileset": "example.foo",
// "error": null,
// "id": "xyz789",
// "modified": "2014-11-21T19:41:10.000Z",
// "created": "2014-11-21T19:41:10.000Z",
// "owner": "example",
// "progress": 0
// }
// ]
});
Returns Promise response
Retrieve state of an upload.
This request requires an access token with the uploads:read scope.
Parameters
upload
String id of the upload to readcallback
Function called with (err, upload)
Examples
var mapboxClient = new MapboxClient('ACCESSTOKEN');
mapboxClient.readUpload('hij456', function(err, upload) {
console.log(upload);
// {
// "complete": true,
// "tileset": "example.markers",
// "error": null,
// "id": "hij456",
// "modified": "2014-11-21T19:41:10.000Z",
// "created": "2014-11-21T19:41:10.000Z",
// "owner": "example",
// "progress": 1
// }
});
Returns Promise response
Encodes the given [latitude, longitude] coordinates array.
Parameters
coordinates
Array<Array<Number>>precision
Number
Returns String
Encodes a GeoJSON LineString feature/geometry.
Parameters
geojson
Objectprecision
Number
Returns String
The JavaScript API to Mapbox services
Parameters
accessToken
string a private or public access tokenoptions
Object additional options provided for configurationoptions.endpoint
[string] location of the Mapbox API pointed-to. This can be customized to point to a Mapbox Atlas Server instance, or a different service, a mock, or a staging endpoint. Usually you don't need to customize this. (optional, defaulthttps://api.mapbox.com
)options.account
[string] account id to use for api requests. If not is specified, the account defaults to the owner of the provided accessToken.
Examples
var client = new MapboxClient('ACCESSTOKEN');
Search for a location with a string, using the Mapbox Geocoding API.
The query
parmeter can be an array of strings only if batch geocoding
is used by specifying mapbox.places-permanent
as the dataset
option.
Parameters
query
string or Array<string> desired locationoptions
[Object] additional options meant to tune the request (optional, default{}
)options.proximity
Object a proximity argument: this is a geographical point given as an object with latitude and longitude properties. Search results closer to this point will be given higher priority.options.bbox
Array a bounding box argument: this is a bounding box given as an array in the format [minX, minY, maxX, maxY]. Search results will be limited to the bounding box.options.types
string a comma seperated list of types that filter results to match those specified. See https://www.mapbox.com/developers/api/geocoding/#filter-type for available types.options.limit
[number] is the maximum number of results to return, between 1 and 10 inclusive. Some very specific queries may return fewer results than the limit. (optional, default5
)options.country
string a comma separated list of country codes to limit results to specified country or countries.options.autocomplete
[boolean] whether to include results that include the query only as a prefix. This is useful for UIs where users type values, but if you have complete addresses as input, you'll want to turn it off (optional, defaulttrue
)options.dataset
[string] the desired data to be geocoded against. The default, mapbox.places, does not permit unlimited caching.mapbox.places-permanent
is available on request and does permit permanent caching. (optional, defaultmapbox.places
)
callback
Function called with (err, results)
Examples
var mapboxClient = new MapboxClient('ACCESSTOKEN');
mapboxClient.geocodeForward('Paris, France', function(err, res) {
// res is a GeoJSON document with geocoding matches
});
// using the proximity option to weight results closer to texas
mapboxClient.geocodeForward('Paris, France', {
proximity: { latitude: 33.6875431, longitude: -95.4431142 }
}, function(err, res) {
// res is a GeoJSON document with geocoding matches
});
// using the bbox option to limit results to a portion of Washington, D.C.
mapboxClient.geocodeForward('Starbucks', {
bbox: [-77.083056,38.908611,-76.997778,38.959167]
}, function(err, res) {
// res is a GeoJSON document with geocoding matches
});
Returns Promise response
Find directions from A to B, or between any number of locations. Consult the Mapbox Directions API for more documentation.
Parameters
waypoints
Array<Object> an array of objects withlatitude
andlongitude
properties that represent waypoints in order. Up to 25 waypoints can be specified.options
[Object] additional options meant to tune the request (optional, default{}
)options.profile
[string] the directions profile, which determines how to prioritize different routes. Options are'driving-traffic'
for automotive routing which factors in current and historic traffic conditions to avoid slowdowns,'driving'
, which assumes transportation via an automobile and will use highways,'walking'
, which avoids streets without sidewalks, and'cycling'
, which prefers streets with bicycle lanes and lower speed limits for transportation via bicycle. (optional, defaultdriving
)options.account
[string] Account for the profile. (optional, defaultmapbox
)options.alternatives
[string] whether to generate alternative routes along with the preferred route. (optional, defaulttrue
)options.geometries
[string] format for the returned route. Options are'geojson'
,'polyline'
, orfalse
:polyline
yields more compact responses which can be decoded on the client side. GeoJSON, the default, is compatible with libraries like Mapbox GL, Leaflet and Mapbox.js.false
omits the geometry entirely and only returns instructions. (optional, defaultgeojson
)options.radiuses
[Array<number or string>] an array of integers in meters indicating the maximum distance each coordinate is allowed to move when snapped to a nearby road segment. There must be as many radiuses as there are coordinates in the request. Values can be any number greater than0
or they can be the stringunlimited
. If no routable road is found within the radius, aNoSegment
error is returned.options.steps
[boolean] whether to return steps and turn-by-turn instructions. Can betrue
orfalse
. (optional, defaultfalse
)options.continue_straight
[boolean] sets allowed direction of travel when departing intermediate waypoints. Iftrue
the route will continue in the same direction of travel. Iffalse
the route may continue in the opposite direction of travel. Defaults totrue
for thedriving
profile andfalse
for thewalking
andcycling
profiles.options.bearings
[Array<Array>] used to filter the road segment the waypoint will be placed on by direction and dictates the angle of approach. This option should always be used in conjunction with theradiuses
option. The parameter takes two values per waypoint: the first is an angle clockwise from true north between0
and360
. The second is the range of degrees the angle can deviate by. We recommend a value of45
or90
for the range, as bearing measurements tend to be inaccurate. This is useful for making sure we reroute vehicles on new routes that continue traveling in their current direction. A request that does this would provide bearing and radius values for the first waypoint and leave the remaining values empty.If provided, the list of bearings must be the same length as the list of waypoints, but you can skip a coordinate and show its position by providing an empty array.options.overview
[string] type of returned overview geometry. Can befull
(the most detailed geometry available),simplified
(a simplified version of the full geometry), orfalse
. (optional, defaultsimplified
)
callback
Function called with (err, results)
Examples
var mapboxClient = new MapboxClient('ACCESSTOKEN');
mapboxClient.getDirections(
[
{ latitude: 33.6, longitude: -95.4431 },
{ latitude: 33.2, longitude: -95.4431 } ],
function(err, res) {
// res is a document with directions
});
// With options
mapboxClient.getDirections([
{ latitude: 33.6875431, longitude: -95.4431142 },
{ latitude: 33.6875431, longitude: -95.4831142 }
], {
profile: 'walking',
alternatives: false,
geometry: 'polyline'
}, function(err, results) {
console.log(results);
});
Returns Promise response
Compute a table of travel-time estimates between a set of waypoints. Consult the Mapbox Matrix API for more documentation and limits.
Parameters
waypoints
Object an array of coordinate object pairs in [longitude, latitude] order.options
[Object] additional options meant to tune the request (optional, default{}
)options.profile
[string] the directions profile, which determines how to prioritize different routes. Options are'driving'
, which assumes transportation via an automobile and will use highways,'walking'
, which avoids streets without sidewalks, and'cycling'
, which prefers streets with bicycle lanes and lower speed limits for transportation via bicycle. The'driving-traffic'
profile is not supported. (optional, defaultdriving
)
callback
Function called with (err, results)
Examples
var mapboxClient = new MapboxClient('ACCESSTOKEN');
// Without options
mapboxClient.getMatrix([{
longitude: -122.42,
latitude: 37.78
},
{
longitude: -122.45,
latitude: 37.91
},
{
longitude: -122.48,
latitude: 37.73
}], {
}, function(err, results) {
console.log(results);
});
// With options
mapboxClient.getMatrix([{
longitude: -122.42,
latitude: 37.78
},
{
longitude: -122.45,
latitude: 37.91
},
{
longitude: -122.48,
latitude: 37.73
}], { profile: 'walking' }, {
}, function(err, results) {
console.log(results);
});
// Results is an object like:
{ durations:
[ [ 0, 1196, 3977, 3415, 5196 ],
[ 1207, 0, 3775, 3213, 4993 ],
[ 3976, 3774, 0, 2650, 2579 ],
[ 3415, 3212, 2650, 0, 3869 ],
[ 5208, 5006, 2579, 3882, 0 ] ] }
// If the coordinates include an un-routable place, then
// the table may contain 'null' values to indicate this, like
{ durations:
[ [ 0, 11642, 57965, null, 72782 ],
[ 11642, 0, 56394, null, 69918 ],
[ 57965, 56394, 0, null, 19284 ],
[ null, null, null, 0, null ],
[ 72782, 69918, 19284, null, 0 ] ] }
Returns Promise response
Determine a URL for a static classic map image, using the Mapbox Static (Classic) Map API.
Parameters
mapid
string a Mapbox map id in username.id formoptions.path.style
Array<Object> optional style definitions for a pathheight
number height of the imageposition
Object or string either an object with longitude and latitude members, or the string 'auto'position.longitude
number east, west bearingposition.latitude
number north, south bearingposition.zoom
number zoom level
width
number width of the imageoptions.format
[string] image format. can be jpg70, jpg80, jpg90, png32, png64, png128, png256 (optional, defaultpng
)options.retina
[boolean] whether to double image pixel density (optional, defaultfalse
)options.markers
[Array<Object>] an array of simple marker objects as an overlay (optional, default[]
)options.geojson
[Object] geojson data for the overlay (optional, default{}
)options.path
[Object] a path and (optional, default{}
)options.path.geojson
Array<Object> data for the path as an array of longitude, latitude objects
options
Object all map options
Examples
var mapboxClient = new MapboxClient('ACCESSTOKEN');
Returns string static classic map url
Determine a URL for a static map image, using the Mapbox Static Map API.
Parameters
username
string Mapbox usernameoptions.before_layer
string value for controlling where the overlay is inserted in the stylewidth
number width of the imageheight
number height of the imageposition
Object or string either an object with longitude and latitude members, or the string 'auto'position.longitude
number east, west bearingposition.latitude
number north, south bearingposition.zoom
number map zoom levelposition.bearing
number map bearing in degrees between 0 and 360position.pitch
number map pitch in degrees between 0 (straight down, no pitch) and 60 (maximum pitch)
styleid
string Mapbox Style IDoptions.retina
[boolean] whether to double image pixel density (optional, defaultfalse
)options.markers
[Array<Object>] an array of simple marker objects as an overlay (optional, default[]
)options.geojson
[Object] geojson data for the overlay (optional, default{}
)options.path
[Object] a path and (optional, default{}
)options.path.geojson
Array<Object> data for the path as an array of longitude, latitude objectsoptions.path.style
Array<Object> optional style definitions for a path
options.attribution
boolean controlling whether there is attribution on the image; defaults to trueoptions.logo
boolean controlling whether there is a Mapbox logo on the image; defaults to trueoptions
Object all map options
Examples
var mapboxClient = new MapboxClient('ACCESSTOKEN');
var url = mapboxClient.getStaticURL('mapbox', 'streets-v10', 600, 400, {
longitude: 151.22,
latitude: -33.87,
zoom: 11
}, {
markers: [{ longitude: 151.22, latitude: -33.87 }],
before_layer: 'housenum-label'
});
// url = https://api.mapbox.com/styles/v1/mapbox/streets-v10/static/pin-l-circle(151.22,-33.87)/151.22,-33.87,11/600x400?access_token=ACCESS_TOKEN&before_layer=housenum-label
Returns string static map url
Snap recorded location traces to roads and paths from OpenStreetMap. Consult the Map Matching API for more documentation.
Parameters
coordinates
Array<Array<number>> an array of coordinate pairs in [longitude, latitude] order. Up to 100 coordinates can be specified.options
[Object] additional options meant to tune the request (optional, default{}
)options.profile
[string] the directions profile, which determines how to prioritize different routes. Options are'driving'
, which assumes transportation via an automobile and will use highways,'walking'
, which avoids streets without sidewalks, and'cycling'
, which prefers streets with bicycle lanes and lower speed limits for transportation via bicycle. (optional, defaultdriving
)options.geometries
[string] format of the returned geometry. Allowed values are:'geojson'
(as LineString),'polyline'
with precision 5,'polyline6'
.'polyline'
yields more compact responses which can be decoded on the client side. GeoJSON, the default, is compatible with libraries like Mapbox GL, Leaflet and Mapbox.js. (optional, defaultgeojson
)options.radiuses
[Array<number>] an array of integers in meters indicating the assumed precision of the used tracking device. There must be as many radiuses as there are coordinates in the request. Values can be a number between 0 and 30. Use higher numbers (20-30) for noisy traces and lower numbers (1-10) for clean traces. The default value is 5.options.steps
[boolean] Whether to return steps and turn-by-turn instructions. Can betrue
orfalse
. (optional, defaultfalse
)options.overview
[string or boolean] type of returned overview geometry. Can be'full'
(the most detailed geometry available),'simplified'
(a simplified version of the full geometry), orfalse
. (optional, defaultsimplified
)options.timestamps
[Array<number>] an array of timestamps corresponding to each coordinate provided in the request; must be numbers in Unix time (seconds since the Unix epoch). There must be as many timestamps as there are coordinates in the request.options.annotations
[Array<string>] an array of fields that return additional metadata for each coordinate along the match geometry. Can be any of'duration'
,'distance'
, or'nodes'
.
callback
Function called with (err, results)
Examples
var mapboxClient = new MapboxClient('ACCESSTOKEN');
mapboxClient.matching([
[-95.4431142, 33.6875431],
[-95.0431142, 33.6875431],
[-95.0431142, 33.0875431],
[-95.0431142, 33.0175431],
[-95.4831142, 33.6875431]
], {
overview: 'full'
}, function(err, res) {
// res is a match response object
});
Returns Promise response
Given a list of locations, retrieve vector tiles, find the nearest spatial features, extract their data values, and then absolute values and optionally interpolated values in-between, if the interpolate option is specified.
Consult the Surface API for more documentation.
Parameters
mapid
string a Mapbox mapid containing vector tiles against which we'll querylayer
string layer within the givenmapid
for which to pull datafields
Array<string> layer within the givenmapid
for which to pull datapath
Array<Object> or string either an encoded polyline, provided as a string, or an array of objects with longitude and latitude properties, similar to waypoints.options
[Object] additional options meant to tune the request (optional, default{}
)options.geojson
[string] whether to return data as a GeoJSON point (optional, defaultfalse
)options.zoom
[string] zoom level at which features are queried (optional, defaultmaximum
)options.interpolate
[boolean] Whether to interpolate between matches in the feature collection. (optional, defaulttrue
)
callback
Function called with (err, results)
Examples
var mapboxClient = new MapboxClient('ACCESSTOKEN');
Returns Promise response
Given a location, determine what geographical features are located there. This uses the Mapbox Geocoding API.
Parameters
location
Object the geographical point to searchlocation.latitude
number decimal degrees latitude, in range -90 to 90location.longitude
number decimal degrees longitude, in range -180 to 180
options
[Object] additional options meant to tune the request. (optional, default{}
)options.types
string a comma seperated list of types that filter results to match those specified. See https://www.mapbox.com/api-documentation/#retrieve-places-near-a-location for available types.options.limit
[number] is the maximum number of results to return, between 1 and 5 inclusive. Requires a single options.types to be specified (see example). (optional, default1
)options.dataset
[string] the desired data to be geocoded against. The default, mapbox.places, does not permit unlimited caching.mapbox.places-permanent
is available on request and does permit permanent caching. (optional, defaultmapbox.places
)
callback
Function called with (err, results)
Examples
var mapboxClient = new MapboxGeocoding('ACCESSTOKEN');
mapboxClient.geocodeReverse(
{ latitude: 33.6875431, longitude: -95.4431142 },
function(err, res) {
// res is a GeoJSON document with geocoding matches
});
var mapboxClient = new MapboxGeocoding('ACCESSTOKEN');
mapboxClient.geocodeReverse(
{ latitude: 33.6875431, longitude: -95.4431142, options: { types: address, limit: 3 } },
function(err, res) {
// res is a GeoJSON document with up to 3 geocoding matches
});
Returns Promise response
To retrieve statistics about a specific tileset.
Parameters
tileset
String the id for the tilesetcallback
Function called with (err, tilestats)
Examples
var client = new MapboxClient('ACCESSTOKEN');
client.getTilestats('tileset-id', function(err, info) {
console.log(info);
// {
// "layerCount": {layer count},
// "layers": [
// {
// "layer": {layer name},
// "geometry": {dominant geometry},
// "count": {feature count},
// "attributeCount": {attribute count}
// "attributes": [
// {
// "attribute": {attribute name},
// "type": {attribute type},
// "count": {unique value count},
// "min": {minimum value if type is number},
// "max": {maximum value if type is number},
// "values": [{...unique values}]
// }
// ]
// }
// ]
// }
});
Returns Promise response
To create or update statistics about a specific tileset.
Parameters
tileset
String the id for the tilesetstatistics
object the statistics to uploadcallback
Function called with (err, tilestats)
Examples
var client = new MapboxClient('ACCESSTOKEN');
client.getTilestats('tileset-id', function(err, stats) {
console.log(stats);
// {
// "account": {account}
// ... see stats example above (for Tilestats#getTilestats)
// }
});
Returns Promise response
Retrieve all tilesets
Parameters
options
[Object] optional optionsoptions.limit
Number Maximum Number of tilesets to return
callback
[Function] called with (err, tilesets, response)
Examples
var MapboxClient = require('mapbox');
var client = new MapboxClient('ACCESSTOKEN');
client.listTilesets(function(err, tilesets) {
console.log(tilesets);
});
Returns Promise response
Retrieve data about specific vector features at a specified location within a vector tileset
Parameters
mapid
String Map ID of the tileset to query (eg. mapbox.mapbox-streets-v7)position
Array An array in the form [longitude, latitude] of the position to queryoptions
[Object] optional optionsoptions.radius
Number Approximate distance in meters to query for featuresoptions.limit
Number Number of features between 1-50 to return
callback
[Function] called with (err, results, response)
Examples
var MapboxClient = require('mapbox');
var client = new MapboxClient('ACCESSTOKEN');
client.tilequery('mapbox.mapbox-streets-v7', [-77, 38], {}, function(err, response) {
console.log(response);
});
Returns Promise response