Home Manual Reference Source


These examples assume that an instance of the api exists and is authenticated. See the node and web authentication examples for more information on authenticating.

Getting a resource

Resources are bound to the base api class by default. Resources can be fetched in two ways; by selecting them (.select) or by fetching them (.get). Selecting them will only set the object's id to it's properties. Fetching a resource

Fetch resource and all it's properties:

api.colors.get(1).then(function(color) {
    console.log(color.id + " " + color.name + ": " + color.hex);

Select the current user to quickly obtain related mapstyle sets:

api.users.select('me').mapstyleSets().then(function(sets) {
    for(var i = 0; i < sets.data.length; i++) {

Selection is only usefull as a stepping stone to related resources that can be easily obtained using the id of the parent. Please refer to the [api documentation] for further reference.

Create a new resource

Create a new color and dump the new resource to the console after saving

var data = {name: 'Smurf', hex: '88CCFF'};

Modify a resource

Change profession of the current user and save it.

api.users.get('me').then(me => {
  me.profession = 'Developer';
  me.save(); // Optional chaining to get the updated resource

Clone a resource

Setting the id to null forces the creation of a new object upon saving.

api.colors.get(1).then(color => {
  color.id = null;


Listing resources with pagination. First page with 5 items per page

api.colors.list(1, 5).then(page => {
  console.log('Got resources:');

  for (var i = 0; i < page.data.length; i++) {

Loop over every page and print the result to the console.

function parsePages(page) {
  for (var i = 0; i < page.data.length; i++) {

  if (page.hasNext) {
    console.log('Grabbing page ' + (page.page + 1));

   .list(1, 50)

Loop over all pages and return the data in a promise

function parsePages(page) {
  var data = [];

  function parse(page) {
      data = data.concat(page.data);

      if(page.hasNext) {
          return page.next().then(parse);
      } else {
          return data;

  return parse(page);

   .list(1, 50)
   .then(d => console.log('Total rows: ' + d.length));

Select current user but do not fetch any info to make fetching resources easier.

api.users.select('me').colors.list().then(page => {


Resource lists can be queried to search for specific records as follows:

var query = {
  name: '^:test',
  scale_min: ['>:1', '<:10'],

The search method is an extension of list. This means that .search({}) is the same as list(). More information about search query formatting can be found in the [api documentation].