mapbox - npm Package Compare versions
Comparing version 0.12.0 to 1.0.0-beta
1222
API.md
@@ -1,2 +0,2 @@ | ||
| ## `bulkFeatureUpdate` | ||
| # bulkFeatureUpdate | ||
@@ -6,19 +6,19 @@ Perform a batch of inserts, updates, and deletes to a dataset in a single combined request. | ||
| There are a number of limits to consider when making this request: | ||
| - you can send a total of 100 changes (sum of puts + deletes) in a single request | ||
| - any 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 | ||
| - you can send a total of 100 changes (sum of puts + deletes) in a single request | ||
| - any 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 | ||
| * `update` **`object`** an object describing features in insert and/or delete | ||
| * `update.put` **`[Array<object>]`** features to insert. Each feature must be a valid GeoJSON feature per http://geojson.org/geojson-spec.html#feature-objects | ||
| * `update.delete` **`[Array<string>]`** ids of features to delete | ||
| * `dataset` **`string`** the id for an existing dataset | ||
| * `callback` **`Function`** called with (err, results) | ||
| **Parameters** | ||
| - `update` **object** an object describing features in insert and/or delete | ||
| - `update.put` **[Array<object>]** features to insert. Each feature must be a valid GeoJSON feature per <http://geojson.org/geojson-spec.html#feature-objects> | ||
| - `update.delete` **[Array<string>]** ids of features to delete | ||
| - `dataset` **string** the id for an existing dataset | ||
| - `callback` **Function** called with (err, results) | ||
| ### Examples | ||
| **Examples** | ||
| ```js | ||
| ```javascript | ||
| var MapboxClient = require('mapbox'); | ||
@@ -89,5 +89,5 @@ var client = new MapboxClient('ACCESSTOKEN'); | ||
| Returns nothing, calls callback | ||
| Returns **undefined** nothing, calls callback | ||
| ## `createDataset` | ||
| # createDataset | ||
@@ -97,13 +97,12 @@ To create a new dataset. Valid properties include title and description (not required). | ||
| ### Parameters | ||
| **Parameters** | ||
| * `options` **`[object]`** an object defining a dataset's properties | ||
| * `options.name` **`[string]`** the dataset's name | ||
| * `options.description` **`[string]`** the dataset's description | ||
| * `callback` **`Function`** called with (err, dataset) | ||
| - `options` **[object]** an object defining a dataset's properties | ||
| - `options.name` **[string]** the dataset's name | ||
| - `options.description` **[string]** the dataset's description | ||
| - `callback` **Function** called with (err, dataset) | ||
| **Examples** | ||
| ### Examples | ||
| ```js | ||
| ```javascript | ||
| var MapboxClient = require('mapbox'); | ||
@@ -124,337 +123,326 @@ var client = new MapboxClient('ACCESSTOKEN'); | ||
| Returns nothing, calls callback | ||
| Returns **undefined** nothing, calls callback | ||
| ## `createUpload` | ||
| # deleteDataset | ||
| Create an new upload with a file previously staged on Amazon S3. | ||
| To delete a particular dataset. | ||
| This request requires an access token with the datasets:write scope. | ||
| This request requires an access token with the uploads:write scope. | ||
| **Parameters** | ||
| ### Parameters | ||
| - `dataset` **string** the id for an existing dataset | ||
| - `callback` **Function** called with (err) | ||
| * `options` **`Object`** an object that defines the upload's properties | ||
| * `options.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** | ||
| ### Examples | ||
| ```js | ||
| 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 | ||
| // } | ||
| ```javascript | ||
| var MapboxClient = require('mapbox'); | ||
| var client = new MapboxClient('ACCESSTOKEN'); | ||
| client.deleteDataset('dataset-id', function(err) { | ||
| if (!err) console.log('deleted!'); | ||
| }); | ||
| ``` | ||
| Returns nothing, calls callback | ||
| Returns **undefined** nothing, calls callback | ||
| ## `createUploadCredentials` | ||
| # deleteFeature | ||
| 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. | ||
| Delete an existing feature from a dataset. | ||
| This request requires an access token with the datasets:write scope. | ||
| This request requires an access token with the uploads:write scope. | ||
| **Parameters** | ||
| ### Parameters | ||
| - `id` **string** the `id` of the feature to read | ||
| - `dataset` **string** the id for an existing dataset | ||
| - `callback` **Function** called with (err) | ||
| * `callback` **`Function`** called with (err, credentials) | ||
| **Examples** | ||
| ### Examples | ||
| ```js | ||
| 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) { | ||
| }); | ||
| ```javascript | ||
| var MapboxClient = require('mapbox'); | ||
| var client = new MapboxClient('ACCESSTOKEN'); | ||
| client.deleteFeature('feature-id', 'dataset-id', function(err, feature) { | ||
| if (!err) console.log('deleted!'); | ||
| }); | ||
| ``` | ||
| Returns nothing, calls callback | ||
| Returns **undefined** nothing, calls callback | ||
| ## `deleteDataset` | ||
| # insertFeature | ||
| To delete a particular dataset. | ||
| 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: | ||
| ### Parameters | ||
| - 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 | ||
| * `dataset` **`string`** the id for an existing dataset | ||
| * `callback` **`Function`** called with (err) | ||
| **Parameters** | ||
| - `feature` **object** the feature to insert. Must be a valid GeoJSON feature per <http://geojson.org/geojson-spec.html#feature-objects> | ||
| - `dataset` **string** the id for an existing dataset | ||
| - `callback` **Function** called with (err, feature) | ||
| ### Examples | ||
| **Examples** | ||
| ```js | ||
| ```javascript | ||
| // Insert a brand new feature without an id | ||
| var MapboxClient = require('mapbox'); | ||
| var client = new MapboxClient('ACCESSTOKEN'); | ||
| client.deleteDataset('dataset-id', function(err) { | ||
| if (!err) console.log('deleted!'); | ||
| 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] | ||
| // } | ||
| // } | ||
| }); | ||
| ``` | ||
| Returns nothing, calls callback | ||
| ## `deleteFeature` | ||
| Delete an existing feature from a dataset. | ||
| This request requires an access token with the datasets:write scope. | ||
| ### Parameters | ||
| * `id` **`string`** the `id` of the feature to read | ||
| * `dataset` **`string`** the id for an existing dataset | ||
| * `callback` **`Function`** called with (err) | ||
| ### Examples | ||
| ```js | ||
| ```javascript | ||
| // 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'); | ||
| client.deleteFeature('feature-id', 'dataset-id', function(err, feature) { | ||
| if (!err) console.log('deleted!'); | ||
| 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 nothing, calls callback | ||
| Returns **undefined** nothing, calls callback | ||
| ## `deleteUpload` | ||
| # listDatasets | ||
| Delete a completed upload. In-progress uploads cannot be deleted. | ||
| To retrieve a listing of datasets for a particular account. | ||
| This request requires an access token with the datasets:read scope. | ||
| This request requires an access token with the uploads:delete scope. | ||
| **Parameters** | ||
| ### Parameters | ||
| - `callback` **Function** called with (err, datasets) | ||
| * `callback` **`Function`** called with (err) | ||
| **Examples** | ||
| ### Examples | ||
| ```js | ||
| var mapboxClient = new MapboxClient('ACCESSTOKEN'); | ||
| mapboxClient.deleteUpload('hij456', function(err) { | ||
| ```javascript | ||
| 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 nothing, calls callback | ||
| Returns **undefined** nothing, calls callback | ||
| ## `geocodeForward` | ||
| # listFeatures | ||
| Search for a location with a string, using the | ||
| [Mapbox Geocoding API](https://www.mapbox.com/developers/api/geocoding/). | ||
| 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 | ||
| **Parameters** | ||
| * `query` **`string`** desired location | ||
| * `options` **`[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.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.country` **`string`** a comma seperated list of country codes to limit results to specified country or countries. | ||
| * `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, default `mapbox.places`) | ||
| * `callback` **`Function`** called with (err, results) | ||
| - `dataset` **string** the id for an existing dataset | ||
| - `options` **[object]** an object for passing pagination arguments | ||
| - `options.reverse` **[boolean]** Set to `true` to reverse the default sort order of the listing. | ||
| - `options.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. | ||
| - `options.start` **[string]** The object id that acts as the cursor for pagination and defines your location in the collection. This argument is exclusive so the object associated with the id provided to the start argument will not be included in the response. | ||
| - `callback` **Function** called with (err, collection) | ||
| **Examples** | ||
| ### Examples | ||
| ```js | ||
| var mapboxClient = new MapboxClient('ACCESSTOKEN'); | ||
| mapboxClient.geocodeForward('Paris, France', function(err, res) { | ||
| // res is a GeoJSON document with geocoding matches | ||
| ```javascript | ||
| 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} | ||
| } | ||
| ] | ||
| } | ||
| }); | ||
| // 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 | ||
| }); | ||
| ``` | ||
| Returns nothing, calls callback | ||
| Returns **undefined** nothing, calls callback | ||
| ## `geocodeReverse` | ||
| # readDataset | ||
| Given a location, determine what geographical features are located | ||
| there. This uses the [Mapbox Geocoding API](https://www.mapbox.com/developers/api/geocoding/). | ||
| To retrieve information about a particular dataset. | ||
| This request requires an access token with the datasets:read scope. | ||
| ### Parameters | ||
| **Parameters** | ||
| * `location` **`Object`** the geographical point to search | ||
| * `location.latitude` **`number`** decimal degrees latitude, in range -90 to 90 | ||
| * `location.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/developers/api/geocoding/#filter-type for available types. | ||
| * `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, default `mapbox.places`) | ||
| * `callback` **`Function`** called with (err, results) | ||
| - `dataset` **string** the id for an existing dataset | ||
| - `callback` **Function** called with (err, dataset) | ||
| **Examples** | ||
| ### Examples | ||
| ```js | ||
| var mapboxClient = new MapboxGeocoder('ACCESSTOKEN'); | ||
| mapboxClient.geocodeReverse( | ||
| { latitude: 33.6875431, longitude: -95.4431142 }, | ||
| function(err, res) { | ||
| // res is a GeoJSON document with geocoding matches | ||
| ```javascript | ||
| 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 nothing, calls callback | ||
| Returns **undefined** nothing, calls callback | ||
| ## `getDirections` | ||
| # readFeature | ||
| Find directions from A to B, or between any number of locations. | ||
| Consult the [Mapbox Directions API](https://www.mapbox.com/developers/api/directions/) | ||
| for more documentation. | ||
| Read an existing feature from a dataset. | ||
| This request requires an access token with the datasets:read scope. | ||
| ### Parameters | ||
| **Parameters** | ||
| * `waypoints` **`Array<Object>`** an array of objects with `latitude` and `longitude` 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 `'mapbox.driving'`, which assumes transportation via an automobile and will use highways, `'mapbox.walking'`, which avoids streets without sidewalks, and `'mapbox.cycling'`, which prefers streets with bicycle lanes and lower speed limits for transportation via bicycle. (optional, default `mapbox.driving`) | ||
| * `options.alternatives` **`[string]`** whether to generate alternative routes along with the preferred route. (optional, default `true`) | ||
| * `options.instructions` **`[string]`** format for turn-by-turn instructions along the route. (optional, default `text`) | ||
| * `options.geometry` **`[string]`** format for the returned route. Options are `'geojson'`, `'polyline'`, or `false`: `polyline` yields more compact responses which can be decoded on the client side. [GeoJSON](http://geojson.org/), the default, is compatible with libraries like [Mapbox GL](https://www.mapbox.com/mapbox-gl/), Leaflet and [Mapbox.js](https://www.mapbox.com/mapbox.js/). `false` omits the geometry entirely and only returns instructions. (optional, default `geojson`) | ||
| * `callback` **`Function`** called with (err, results) | ||
| - `id` **string** the `id` of the feature to read | ||
| - `dataset` **string** the id for an existing dataset | ||
| - `callback` **Function** called with (err, feature) | ||
| **Examples** | ||
| ### Examples | ||
| ```js | ||
| 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 | ||
| ```javascript | ||
| 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] | ||
| // } | ||
| // } | ||
| }); | ||
| // With options | ||
| mapboxClient.getDirections([ | ||
| { latitude: 33.6875431, longitude: -95.4431142 }, | ||
| { latitude: 33.6875431, longitude: -95.4831142 } | ||
| ], { | ||
| profile: 'mapbox.walking', | ||
| instructions: 'html', | ||
| alternatives: false, | ||
| geometry: 'polyline' | ||
| }, function(err, results) { | ||
| console.log(results.origin); | ||
| }); | ||
| ``` | ||
| Returns nothing, calls callback | ||
| Returns **undefined** nothing, calls callback | ||
| ## `getDistances` | ||
| # updateDataset | ||
| Compute a table of travel-time estimates between a set of waypoints. | ||
| Consult the [Mapbox Distance API](https://www.mapbox.com/developers/api/distance/) | ||
| for more documentation. | ||
| To make updates to a particular dataset's properties. | ||
| This request requires an access token with the datasets:write scope. | ||
| ### Parameters | ||
| **Parameters** | ||
| * `waypoints` **`Array<Array<number>>`** an array of coordinate pairs in [longitude, latitude] order. Up to 100 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'`, 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, default `driving`) | ||
| * `callback` **`Function`** called with (err, results) | ||
| - `dataset` **string** the id for an existing dataset | ||
| - `options` **[object]** an object defining updates to the dataset's properties | ||
| - `options.name` **[string]** the updated dataset's name | ||
| - `options.description` **[string]** the updated dataset's description | ||
| - `callback` **Function** called with (err, dataset) | ||
| **Examples** | ||
| ### Examples | ||
| ```js | ||
| var mapboxClient = new MapboxClient('ACCESSTOKEN'); | ||
| // With options | ||
| mapboxClient.getDistances([ | ||
| [-95.4431142, 33.6875431], | ||
| [-95.0431142, 33.6875431], | ||
| [-95.0431142, 33.0875431], | ||
| [-95.0431142, 33.0175431], | ||
| [-95.4831142, 33.6875431] | ||
| ], { | ||
| profile: 'walking' | ||
| }, function(err, results) { | ||
| console.log(results); | ||
| ```javascript | ||
| 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} | ||
| // } | ||
| }); | ||
| // 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 nothing, calls callback | ||
| Returns **undefined** nothing, calls callback | ||
| ## `getTilestats` | ||
| # getTilestats | ||
| To retrieve statistics about a specific tileset. | ||
| ### Parameters | ||
| **Parameters** | ||
| * `tileset` **`String`** the id for the tileset | ||
| * `callback` **`Function`** called with (err, tilestats) | ||
| - `tileset` **String** the id for the tileset | ||
| - `callback` **Function** called with (err, tilestats) | ||
| **Examples** | ||
| ### Examples | ||
| ```js | ||
| ```javascript | ||
| var client = new MapboxClient('ACCESSTOKEN'); | ||
@@ -486,5 +474,5 @@ client.getTilestats('tileset-id', function(err, info) { | ||
| Returns nothing, calls callback | ||
| Returns **undefined** nothing, calls callback | ||
| ## `getTilestatsAttribute` | ||
| # getTilestatsAttribute | ||
@@ -494,13 +482,12 @@ To retrieve statistics about the attribute values of a particular attribute | ||
| ### Parameters | ||
| **Parameters** | ||
| * `tileset` **`String`** the id for the tileset | ||
| * `layer` **`String`** the name of the layer in the tileset | ||
| * `attribute` **`String`** the name of the attribute in the layer | ||
| * `callback` **`Function`** called with (err) | ||
| - `tileset` **String** the id for the tileset | ||
| - `layer` **String** the name of the layer in the tileset | ||
| - `attribute` **String** the name of the attribute in the layer | ||
| - `callback` **Function** called with (err) | ||
| **Examples** | ||
| ### Examples | ||
| ```js | ||
| ```javascript | ||
| var client = new MapboxClient('ACCESSTOKEN'); | ||
@@ -525,173 +512,122 @@ client.getTilestatsAttribute('tileset-id', 'layer-name', 'attr-name', function(err, info) { | ||
| Returns nothing, calls callback | ||
| Returns **undefined** nothing, calls callback | ||
| ## `insertFeature` | ||
| # createUpload | ||
| 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 | ||
| Create an new upload with a file previously staged on Amazon S3. | ||
| ### Parameters | ||
| This request requires an access token with the uploads:write scope. | ||
| * `feature` **`object`** the feature to insert. Must be a valid GeoJSON feature per http://geojson.org/geojson-spec.html#feature-objects | ||
| * `dataset` **`string`** the id for an existing dataset | ||
| * `callback` **`Function`** called with (err, feature) | ||
| **Parameters** | ||
| - `options` **Object** an object that defines the upload's properties | ||
| - `options.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 | ||
| **Examples** | ||
| ```js | ||
| // 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] | ||
| } | ||
| ```javascript | ||
| 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}" | ||
| }; | ||
| client.insertFeature(feature, 'dataset-id', function(err, feature) { | ||
| console.log(feature); | ||
| mapboxClient.createUpload({ | ||
| tileset: [accountid, 'mytileset'].join('.'), | ||
| url: credentials.url | ||
| }, function(err, upload) { | ||
| console.log(upload); | ||
| // { | ||
| // "id": {feature id}, | ||
| // "type": "Feature", | ||
| // "properties": { | ||
| // "name": "Null Island" | ||
| // }, | ||
| // "geometry": { | ||
| // "type": "Point", | ||
| // "coordinates": [0, 0] | ||
| // } | ||
| // "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 | ||
| // } | ||
| }); | ||
| ``` | ||
| ```js | ||
| // 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 nothing, calls callback | ||
| Returns **undefined** nothing, calls callback | ||
| ## `listDatasets` | ||
| # createUploadCredentials | ||
| To retrieve a listing of datasets for a particular account. | ||
| This request requires an access token with the datasets:read scope. | ||
| 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. | ||
| ### Parameters | ||
| This request requires an access token with the uploads:write scope. | ||
| * `callback` **`Function`** called with (err, datasets) | ||
| **Parameters** | ||
| - `callback` **Function** called with (err, credentials) | ||
| ### Examples | ||
| **Examples** | ||
| ```js | ||
| 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} | ||
| // } | ||
| // ] | ||
| ```javascript | ||
| 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 nothing, calls callback | ||
| Returns **undefined** nothing, calls callback | ||
| ## `listFeatures` | ||
| # deleteUpload | ||
| 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. | ||
| Delete a completed upload. In-progress uploads cannot be deleted. | ||
| ### Parameters | ||
| This request requires an access token with the uploads:delete scope. | ||
| * `dataset` **`string`** the id for an existing dataset | ||
| * `options` **`[object]`** an object for passing pagination arguments | ||
| * `options.reverse` **`[boolean]`** Set to `true` to reverse the default sort order of the listing. | ||
| * `options.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. | ||
| * `options.start` **`[string]`** The object id that acts as the cursor for pagination and defines your location in the collection. This argument is exclusive so the object associated with the id provided to the start argument will not be included in the response. | ||
| * `callback` **`Function`** called with (err, collection) | ||
| **Parameters** | ||
| - `upload` | ||
| - `callback` **Function** called with (err) | ||
| ### Examples | ||
| **Examples** | ||
| ```js | ||
| 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} | ||
| } | ||
| ] | ||
| } | ||
| ```javascript | ||
| var mapboxClient = new MapboxClient('ACCESSTOKEN'); | ||
| mapboxClient.deleteUpload('hij456', function(err) { | ||
| }); | ||
| ``` | ||
| Returns nothing, calls callback | ||
| Returns **undefined** nothing, calls callback | ||
| ## `listUploads` | ||
| # listUploads | ||
@@ -702,10 +638,9 @@ Retrieve a listing of uploads for a particular account. | ||
| ### Parameters | ||
| **Parameters** | ||
| * `callback` **`Function`** called with (err, uploads) | ||
| - `callback` **Function** called with (err, uploads) | ||
| **Examples** | ||
| ### Examples | ||
| ```js | ||
| ```javascript | ||
| var mapboxClient = new MapboxClient('ACCESSTOKEN'); | ||
@@ -739,175 +674,286 @@ mapboxClient.listUploads(function(err, uploads) { | ||
| Returns nothing, calls callback | ||
| Returns **undefined** nothing, calls callback | ||
| ## `MapboxClient` | ||
| # readUpload | ||
| The JavaScript API to Mapbox services | ||
| Retrieve state of an upload. | ||
| ### Parameters | ||
| This request requires an access token with the uploads:read scope. | ||
| * `accessToken` **`string`** a private or public access token | ||
| * `options` **`Object`** additional options provided for configuration | ||
| * `options.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, default `https://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. | ||
| **Parameters** | ||
| - `upload` **String** id of the upload to read | ||
| - `callback` **Function** called with (err, upload) | ||
| ### Examples | ||
| **Examples** | ||
| ```js | ||
| var client = new MapboxClient('ACCESSTOKEN'); | ||
| ```javascript | ||
| 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 **undefined** nothing, calls callback | ||
| | type | description | | ||
| | ---- | ----------- | | ||
| | `Error` | if accessToken is not provided | | ||
| ## `matching` | ||
| # MapboxClient | ||
| Snap recorded location traces to roads and paths from OpenStreetMap. | ||
| Consult the [Map Matching API](https://www.mapbox.com/developers/api/map-matching/) | ||
| for more documentation. | ||
| The JavaScript API to Mapbox services | ||
| ### Parameters | ||
| **Parameters** | ||
| * `trace` **`Object`** a single [GeoJSON](http://geojson.org/) Feature with a LineString geometry, containing up to 100 positions. | ||
| * `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 `'mapbox.driving'`, which assumes transportation via an automobile and will use highways, `'mapbox.walking'`, which avoids streets without sidewalks, and `'mapbox.cycling'`, which prefers streets with bicycle lanes and lower speed limits for transportation via bicycle. (optional, default `mapbox.driving`) | ||
| * `options.geometry` **`[string]`** format for the returned route. Options are `'geojson'`, `'polyline'`, or `false`: `polyline` yields more compact responses which can be decoded on the client side. [GeoJSON](http://geojson.org/), the default, is compatible with libraries like [Mapbox GL](https://www.mapbox.com/mapbox-gl/), Leaflet and [Mapbox.js](https://www.mapbox.com/mapbox.js/). `false` omits the geometry entirely and only returns matched points. (optional, default `geojson`) | ||
| * `options.gps_precision` **`[number]`** An integer in meters indicating the assumed precision of the used tracking device. Use higher numbers (5-10) for noisy traces and lower numbers (1-3) for clean traces. The default value is 4. (optional, default `4`) | ||
| * `callback` **`Function`** called with (err, results) | ||
| - `accessToken` **string** a private or public access token | ||
| - `options` **Object** additional options provided for configuration | ||
| - `options.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, default `https://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** | ||
| ### Examples | ||
| ```javascript | ||
| var client = new MapboxClient('ACCESSTOKEN'); | ||
| ``` | ||
| ```js | ||
| ## geocodeForward | ||
| Search for a location with a string, using the | ||
| [Mapbox Geocoding API](https://www.mapbox.com/developers/api/geocoding/). | ||
| **Parameters** | ||
| - `query` **string** desired location | ||
| - `options` **[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.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.country` **string** a comma seperated list of country codes to | ||
| limit results to specified country or countries. | ||
| - `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, default `mapbox.places`) | ||
| - `callback` **Function** called with (err, results) | ||
| **Examples** | ||
| ```javascript | ||
| var mapboxClient = new MapboxClient('ACCESSTOKEN'); | ||
| mapboxClient.matching({ | ||
| "type": "Feature", | ||
| "properties": { | ||
| "coordTimes": [ | ||
| "2015-04-21T06:00:00Z", | ||
| "2015-04-21T06:00:05Z", | ||
| "2015-04-21T06:00:10Z", | ||
| "2015-04-21T06:00:15Z", | ||
| "2015-04-21T06:00:20Z" | ||
| ] | ||
| }, | ||
| "geometry": { | ||
| "type": "LineString", | ||
| "coordinates": [ | ||
| [ 13.418946862220764, 52.50055852688439 ], | ||
| [ 13.419011235237122, 52.50113000479732 ], | ||
| [ 13.419756889343262, 52.50171780290061 ], | ||
| [ 13.419885635375975, 52.50237416816131 ], | ||
| [ 13.420631289482117, 52.50294888790448 ] | ||
| ] | ||
| } | ||
| }, | ||
| function(err, res) { | ||
| // res is a document with directions | ||
| 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 | ||
| }); | ||
| ``` | ||
| Returns nothing, calls callback | ||
| Returns **undefined** nothing, calls callback | ||
| ## `readDataset` | ||
| ## getDirections | ||
| To retrieve information about a particular dataset. | ||
| This request requires an access token with the datasets:read scope. | ||
| Find directions from A to B, or between any number of locations. | ||
| Consult the [Mapbox Directions API](https://www.mapbox.com/developers/api/directions/) | ||
| for more documentation. | ||
| ### Parameters | ||
| **Parameters** | ||
| * `dataset` **`string`** the id for an existing dataset | ||
| * `callback` **`Function`** called with (err, dataset) | ||
| - `waypoints` **Array<Object>** an array of objects with `latitude` | ||
| and `longitude` 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 `'mapbox.driving'`, which assumes transportation via an | ||
| automobile and will use highways, `'mapbox.walking'`, which avoids | ||
| streets without sidewalks, and `'mapbox.cycling'`, which prefers streets | ||
| with bicycle lanes and lower speed limits for transportation via | ||
| bicycle. (optional, default `mapbox.driving`) | ||
| - `options.alternatives` **[string]** whether to generate | ||
| alternative routes along with the preferred route. (optional, default `true`) | ||
| - `options.instructions` **[string]** format for turn-by-turn | ||
| instructions along the route. (optional, default `text`) | ||
| - `options.geometry` **[string]** format for the returned | ||
| route. Options are `'geojson'`, `'polyline'`, or `false`: `polyline` | ||
| yields more compact responses which can be decoded on the client side. | ||
| [GeoJSON](http://geojson.org/), the default, is compatible with libraries | ||
| like [Mapbox GL](https://www.mapbox.com/mapbox-gl/), | ||
| Leaflet and [Mapbox.js](https://www.mapbox.com/mapbox.js/). `false` | ||
| omits the geometry entirely and only returns instructions. (optional, default `geojson`) | ||
| - `callback` **Function** called with (err, results) | ||
| **Examples** | ||
| ### Examples | ||
| ```javascript | ||
| 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 | ||
| }); | ||
| ```js | ||
| 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} | ||
| // } | ||
| // With options | ||
| mapboxClient.getDirections([ | ||
| { latitude: 33.6875431, longitude: -95.4431142 }, | ||
| { latitude: 33.6875431, longitude: -95.4831142 } | ||
| ], { | ||
| profile: 'mapbox.walking', | ||
| instructions: 'html', | ||
| alternatives: false, | ||
| geometry: 'polyline' | ||
| }, function(err, results) { | ||
| console.log(results.origin); | ||
| }); | ||
| ``` | ||
| Returns nothing, calls callback | ||
| Returns **undefined** nothing, calls callback | ||
| ## `readFeature` | ||
| ## getDistances | ||
| Read an existing feature from a dataset. | ||
| This request requires an access token with the datasets:read scope. | ||
| Compute a table of travel-time estimates between a set of waypoints. | ||
| Consult the [Mapbox Distance API](https://www.mapbox.com/developers/api/distance/) | ||
| for more documentation. | ||
| ### Parameters | ||
| **Parameters** | ||
| * `id` **`string`** the `id` of the feature to read | ||
| * `dataset` **`string`** the id for an existing dataset | ||
| * `callback` **`Function`** called with (err, feature) | ||
| - `waypoints` **Array<Array<number>>** an array of coordinate pairs | ||
| in [longitude, latitude] order. Up to | ||
| 100 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'`, 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, default `driving`) | ||
| - `callback` **Function** called with (err, results) | ||
| **Examples** | ||
| ### Examples | ||
| ```js | ||
| 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] | ||
| // } | ||
| // } | ||
| ```javascript | ||
| var mapboxClient = new MapboxClient('ACCESSTOKEN'); | ||
| // With options | ||
| mapboxClient.getDistances([ | ||
| [-95.4431142, 33.6875431], | ||
| [-95.0431142, 33.6875431], | ||
| [-95.0431142, 33.0875431], | ||
| [-95.0431142, 33.0175431], | ||
| [-95.4831142, 33.6875431] | ||
| ], { | ||
| profile: 'walking' | ||
| }, function(err, results) { | ||
| console.log(results); | ||
| }); | ||
| ``` | ||
| Returns nothing, calls callback | ||
| // 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 ] ] } | ||
| ## `readUpload` | ||
| // 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 ] ] } | ||
| ``` | ||
| Retrieve state of an upload. | ||
| Returns **undefined** nothing, calls callback | ||
| This request requires an access token with the uploads:read scope. | ||
| ## matching | ||
| ### Parameters | ||
| Snap recorded location traces to roads and paths from OpenStreetMap. | ||
| Consult the [Map Matching API](https://www.mapbox.com/developers/api/map-matching/) | ||
| for more documentation. | ||
| * `upload` **`String`** id of the upload to read | ||
| * `callback` **`Function`** called with (err, upload) | ||
| **Parameters** | ||
| - `trace` **Object** a single [GeoJSON](http://geojson.org/) | ||
| Feature with a LineString geometry, containing up to 100 positions. | ||
| - `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 `'mapbox.driving'`, which assumes transportation via an | ||
| automobile and will use highways, `'mapbox.walking'`, which avoids | ||
| streets without sidewalks, and `'mapbox.cycling'`, which prefers streets | ||
| with bicycle lanes and lower speed limits for transportation via | ||
| bicycle. (optional, default `mapbox.driving`) | ||
| - `options.geometry` **[string]** format for the returned | ||
| route. Options are `'geojson'`, `'polyline'`, or `false`: `polyline` | ||
| yields more compact responses which can be decoded on the client side. | ||
| [GeoJSON](http://geojson.org/), the default, is compatible with libraries | ||
| like [Mapbox GL](https://www.mapbox.com/mapbox-gl/), | ||
| Leaflet and [Mapbox.js](https://www.mapbox.com/mapbox.js/). `false` | ||
| omits the geometry entirely and only returns matched points. (optional, default `geojson`) | ||
| - `options.gps_precision` **[number]** An integer in meters indicating | ||
| the assumed precision of the used tracking device. Use higher | ||
| numbers (5-10) for noisy traces and lower numbers (1-3) for clean | ||
| traces. The default value is 4. (optional, default `4`) | ||
| - `callback` **Function** called with (err, results) | ||
| ### Examples | ||
| **Examples** | ||
| ```js | ||
| ```javascript | ||
| 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 | ||
| // } | ||
| mapboxClient.matching({ | ||
| "type": "Feature", | ||
| "properties": { | ||
| "coordTimes": [ | ||
| "2015-04-21T06:00:00Z", | ||
| "2015-04-21T06:00:05Z", | ||
| "2015-04-21T06:00:10Z", | ||
| "2015-04-21T06:00:15Z", | ||
| "2015-04-21T06:00:20Z" | ||
| ] | ||
| }, | ||
| "geometry": { | ||
| "type": "LineString", | ||
| "coordinates": [ | ||
| [ 13.418946862220764, 52.50055852688439 ], | ||
| [ 13.419011235237122, 52.50113000479732 ], | ||
| [ 13.419756889343262, 52.50171780290061 ], | ||
| [ 13.419885635375975, 52.50237416816131 ], | ||
| [ 13.420631289482117, 52.50294888790448 ] | ||
| ] | ||
| } | ||
| }, | ||
| function(err, res) { | ||
| // res is a document with directions | ||
| }); | ||
| ``` | ||
| Returns nothing, calls callback | ||
| Returns **undefined** nothing, calls callback | ||
| ## `surface` | ||
| ## surface | ||
@@ -921,57 +967,63 @@ Given a list of locations, retrieve vector tiles, find the nearest | ||
| ### Parameters | ||
| **Parameters** | ||
| * `mapid` **`string`** a Mapbox mapid containing vector tiles against which we'll query | ||
| * `layer` **`string`** layer within the given `mapid` for which to pull data | ||
| * `fields` **`Array<string>`** layer within the given `mapid` for which to pull data | ||
| * `path` **`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, default `false`) | ||
| * `options.zoom` **`[string]`** zoom level at which features are queried (optional, default `maximum`) | ||
| * `options.interpolate` **`[boolean]`** Whether to interpolate between matches in the feature collection. (optional, default `true`) | ||
| * `callback` **`Function`** called with (err, results) | ||
| - `mapid` **string** a Mapbox mapid containing vector tiles against | ||
| which we'll query | ||
| - `layer` **string** layer within the given `mapid` for which to pull | ||
| data | ||
| - `fields` **Array<string>** layer within the given `mapid` for which to pull | ||
| data | ||
| - `path` **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, default `false`) | ||
| - `options.zoom` **[string]** zoom level at which features | ||
| are queried (optional, default `maximum`) | ||
| - `options.interpolate` **[boolean]** Whether to interpolate | ||
| between matches in the feature collection. (optional, default `true`) | ||
| - `callback` **Function** called with (err, results) | ||
| **Examples** | ||
| ### Examples | ||
| ```js | ||
| ```javascript | ||
| var mapboxClient = new MapboxClient('ACCESSTOKEN'); | ||
| ``` | ||
| Returns nothing, calls callback | ||
| Returns **undefined** nothing, calls callback | ||
| ## `updateDataset` | ||
| # geocodeReverse | ||
| To make updates to a particular dataset's properties. | ||
| This request requires an access token with the datasets:write scope. | ||
| Given a location, determine what geographical features are located | ||
| there. This uses the [Mapbox Geocoding API](https://www.mapbox.com/developers/api/geocoding/). | ||
| ### Parameters | ||
| **Parameters** | ||
| * `dataset` **`string`** the id for an existing dataset | ||
| * `options` **`[object]`** an object defining updates to the dataset's properties | ||
| * `options.name` **`[string]`** the updated dataset's name | ||
| * `options.description` **`[string]`** the updated dataset's description | ||
| * `callback` **`Function`** called with (err, dataset) | ||
| - `location` **Object** the geographical point to search | ||
| - `location.latitude` **number** decimal degrees latitude, in range -90 to 90 | ||
| - `location.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/developers/api/geocoding/#filter-type> | ||
| for available types. | ||
| - `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, default `mapbox.places`) | ||
| - `callback` **Function** called with (err, results) | ||
| **Examples** | ||
| ### Examples | ||
| ```js | ||
| 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} | ||
| // } | ||
| ```javascript | ||
| var mapboxClient = new MapboxGeocoding('ACCESSTOKEN'); | ||
| mapboxClient.geocodeReverse( | ||
| { latitude: 33.6875431, longitude: -95.4431142 }, | ||
| function(err, res) { | ||
| // res is a GeoJSON document with geocoding matches | ||
| }); | ||
| ``` | ||
| Returns nothing, calls callback | ||
| Returns **undefined** nothing, calls callback |
@@ -0,1 +1,7 @@ | ||
| ## 1.0.0-beta | ||
| - Changes a major API! Geocoding is now named geocoding everywhere, so the | ||
| sub-require is `mapbox/lib/services/geocoding`, not, like it used to be, | ||
| `mapbox/lib/services/geocoder` | ||
| ## 0.12.0 | ||
@@ -2,0 +8,0 @@ |
@@ -5,4 +5,4 @@ // We keep all of the constants that declare endpoints in one | ||
| module.exports.DEFAULT_ENDPOINT = 'https://api.mapbox.com'; | ||
| module.exports.API_GEOCODER_FORWARD = '/geocoding/v5/{dataset}/{query}.json{?proximity,country,types}'; | ||
| module.exports.API_GEOCODER_REVERSE = '/geocoding/v5/{dataset}/{longitude},{latitude}.json{?types}'; | ||
| module.exports.API_GEOCODING_FORWARD = '/geocoding/v5/{dataset}/{query}.json{?proximity,country,types}'; | ||
| module.exports.API_GEOCODING_REVERSE = '/geocoding/v5/{dataset}/{longitude},{latitude}.json{?types}'; | ||
| module.exports.API_DIRECTIONS = '/v4/directions/{profile}/{encodedWaypoints}.json{?alternatives,instructions,geometry,steps}'; | ||
@@ -9,0 +9,0 @@ module.exports.API_DISTANCE = '/distances/v1/mapbox/{profile}'; |
@@ -5,3 +5,3 @@ 'use strict'; | ||
| var xtend = require('xtend/mutable'); | ||
| var MapboxGeocoder = require('./services/geocoder'); | ||
| var MapboxGeocoding = require('./services/geocoding'); | ||
| var MapboxSurface = require('./services/surface'); | ||
@@ -38,3 +38,3 @@ var MapboxDirections = require('./services/directions'); | ||
| MapboxClient.prototype, | ||
| MapboxGeocoder.prototype, | ||
| MapboxGeocoding.prototype, | ||
| MapboxSurface.prototype, | ||
@@ -41,0 +41,0 @@ MapboxDirections.prototype, |
| { | ||
| "name": "mapbox", | ||
| "version": "0.12.0", | ||
| "version": "1.0.0-beta", | ||
| "description": "interface to mapbox services", | ||
@@ -5,0 +5,0 @@ "main": "lib/mapbox.js", |
@@ -68,3 +68,3 @@ # mapbox-sdk-js | ||
| * geocoder: `require('mapbox/lib/services/geocoder')` | ||
| * geocoding: `require('mapbox/lib/services/geocoding')` | ||
| * surface: `require('mapbox/lib/services/surface')` | ||
@@ -71,0 +71,0 @@ * matching: `require('mapbox/lib/services/matching')` |
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Fixed alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Deprecated
MaintenanceThe maintainer of the package marked it as deprecated. This could indicate that a single version should not be used, or that the package is no longer maintained and any new vulnerabilities will not be fixed.
Found 1 instance in 1 package
Improved metrics
- Total package byte prevSize
- increased by0.24%
502614
- Number of medium maintenance alerts
- decreased by-100%
0
No dependency changes