Nail Polishing Minions

    cartodb

    0.5.1 • Public • Published

    CartoDB client for node.js

    This library abstracts calls to CartoDB's SQL, Import, and Maps APIs.

    Install

    npm install cartodb

    Usage

    Here's a simple example to make a SQL API call.

    var CartoDB = require('cartodb');
    
    var sql = new CartoDB.SQL({user:{USERNAME}})
    
    sql.execute("SELECT * FROM mytable LIMIT 10")
      //you can listen for 'done' and 'error' promise events
      .done(function(data) {
        console.log(data) //data.rows is an array with an object for each row in your result set
      });
    
    

    SQL Module

    Methods

    constructor

    var sql = new CartoDB.SQL({
      user: {USERNAME},
      api_key: {APIKEY}
    });
    

    Note: api_key is only required for a write query.

    SQL.execute

    SQL.execute(sql [,vars][, options][, callback])

    vars - An object of variables to be rendered with sql using Mustache

    options - An object for options for the API call. Default is json.

    {
      format: 'json'|'csv'|'geojson'|'shp'|'svg'|'kml'|'SpatiaLite'
    }
    

    More details about formats : CartoDB SQL API docs

    callback - A function that the data object will be passed to if the API call is successful.

    This will return a promise. .done() and .error() can be chained after SQL.execute().

    .done() first argument will be either : an object containing (when using json format) or a raw string (when using all other formats).

    var sql = new CartoDB.SQL({user:{USERNAME});
    sql.execute("SELECT * from {{table}} LIMIT 5")
      .done(function(data) {
        console.log(`Executed in ${data.time}, total rows: ${data.total_rows}`);
        console.log(data.rows[0].cartodb_id)
      })
      .error(function(error) {
        //error contains the error message
      });
    
    var sql = new CartoDB.SQL({user:{USERNAME}});
    sql.execute("SELECT * from {{table}} LIMIT 5", { format: 'csv' })
      .done(function(data) {
        console.log('raw CSV data :');
        console.log(data);
      });
    

    Piping

    You can pipe data from the SQL.execute()

    var file = require('fs').createWriteStream(__dirname + '/output.json');
    
    var sql = new CartoDB.SQL({user:{USERNAME}, api_key:{APIKEY}});
    
    sql.execute("SELECT * from {{table}} LIMIT 5", {table: 'all_month'})
    
    
    sql.pipe(file);
    

    Import Module

    Methods

    file - Import a file from the filesystem - This method is the same as dragging a file (CSV,ZIP,XLS,KML) into the CartoDB GUI. The end result is a table in your account.

    This method takes the path to your file and results in a table_name for the newly-created table.

    Import.file(filePath, options)

    .done() and .error() can be chained after Import.file().

    url - Import a file from URL - This method is the same as specifying a publicly accessible url to import in the CartoDB GUI. The end result is a table in your account.

    This method takes the URL to your file and results in a table_name for the newly-created table.

    Import.url(url, options)

    .done() and .error() can be chained after Import.url().

    var importer = new CartoDB.Import({user:{USERNAME}, api_key:{APIKEY}});
    var path = require('path');
    
    importer
      .file(path.join(__dirname, 'all_week.csv'), {
        privacy: 'public'
      })
      .done(function(table_name) {
        console.log('Table ' + table_name + ' has been created!');
      });
    
    

    Named Maps Module

    Constructor

    Pass in a config object with user and api_key

    var namedMaps = new CartoDB.Maps.Named({
        user: 'username',
        api_key: 'yourreallylongcartodbapikey'
    });
    

    Methods

    All methods create a promise, and you can listen for done and _error events.

    Named.create() - Create a named map by providing a JSON template

    Named Map Template:

    {
      "version": "0.0.1",
      "name": "world_borders",
      "auth": {
        "method": "token",
        "valid_tokens": [
          "auth_token1",
          "auth_token2"
        ]
      },
      "placeholders": {
        "color": {
          "type": "css_color",
          "default": "red"
        },
        "cartodb_id": {
          "type": "number",
          "default": 1
        }
      },
      "layergroup": {
        "version": "1.0.1",
        "layers": [
          {
            "type": "cartodb",
            "options": {
              "cartocss_version": "2.1.1",
              "cartocss": "/** category visualization */ #world_borders { polygon-opacity: 1; line-color: #FFF; line-width: 0; line-opacity: 1; } #world_borders[cat=0] { polygon-fill: #A6CEE3; } #world_borders[cat=1] { polygon-fill: #1F78B4; } #world_borders[cat=2] { polygon-fill: #2167AB; } #world_borders[cat=3] { polygon-fill: #5077b5; }",
              "sql": "SELECT *, mod(cartodb_id,4) as cat FROM world_borders"
            }
          }
        ]
      },
      "view": {
        "zoom": 4,
        "center": {
          "lng": 0,
          "lat": 0
        },
        "bounds": {
          "west": -45,
          "south": -45,
          "east": 45,
          "north": 45
        }
      }
    }
    
    namedMaps.create({
       template: template
     })
       .on('done', function(res) {
        console.log(res)
      })
    

    Response:

    { template_id: 'world_borders' }
    

    Named.instantiate() - Instantiate a named map to get a layergroupid, passing an options object with the template_id, auth_token (if required), and placeholder params (if needed by your named map template)

    namedMaps.instantiate({
      template_id: 'world_borders',
      auth_token: 'auth_token1',
      params: {
        color: '#ff0000',
        cartodb_id: 3
      }
    })
      .on('done', function(res) {
        console.log(res)
      })
    

    Response:

    { layergroupid: 'chriswhong@72f19e2f@28aa9b31a7147f1d370f0f6322e16de6:1453321153152',
      metadata: { layers: [ [Object] ] },
      cdn_url:
       { http: 'ashbu.cartocdn.com',
         https: 'cartocdn-ashbu.global.ssl.fastly.net' },
      last_updated: '2016-01-20T20:19:13.152Z' }
    

    Named.update() - Update a Named Map template

    namedMaps.update({
      template: template
    })
      .on('done', function(res) {
        console.log(res)
      })
    

    Response:

    { template_id: 'world_borders' }
    

    Named.delete() - Delete a named map - pass it an options object with template_id

    namedMaps.delete({
      template_id: 'world_borders'
    })
      .on('done', function(template_id) {
        console.log(template_id);
      })
    

    Response is the template_id that was just deleted:

    world_borders
    

    Named.list() - Get a list of all named maps in your account

    namedMaps.list()
      .on('done', function(res) {
        console.log(res);
      });
    

    Named.definition() - Get the current template for a named map

    namedMaps.definition({
      template_id: 'world_borders'
    })
      .on('done', function(res) {
        console.log(res);
      });
    

    Command-line access

    SQL Module: cartodb / cartodb-sql

    Options
    
      -s, --sql string       A SQL query (required).
      -u, --user string      Your CartoDB username.
      -a, --api_key string   Your CartoDB API Key (only needed for write operations).
      -f, --format string    Output format json|csv|geojson|shp|svg|kml|SpatiaLite
      -o, --output string    Output file. If omitted will use stdout.
      -c, --config string    Config file. Use a JSON file as a way to input these arguments. If no username nor config file is provided, it will look for "config.json" by default.
      -h, --help
    

    Examples

    $ cartodb -u nerik -f svg 'SELECT * FROM europe' > europe.svg
    $ cartodb -u nerik -f csv 'SELECT cartodb_id, admin, adm_code FROM europe LIMIT 5' -o europe.csv
    $ cartodb -c config.json 'UPDATE ...' #hide your api_key in this file !
    $ cartodb 'UPDATE ...' # "config.json" will be used for credentials by default
    
    

    Import Module: cartodb-import

    Options
    
      -f, --file string      Path to a local file to import.
      -l, --url string       URL to import.
      -p, --privacy string   Privacy of the generated table (public|private)
      -u, --user string      Your CartoDB username
      -a, --api_key string   Your CartoDB API Key (only needed for write operations)
      -c, --config string    Config file. Use a JSON file as a way to input these arguments.
      -h, --help
    

    Examples

    $ cartodb-import -u nerik --api_key XXX test.csv
    $ cartodb-import -c config.json test.csv
    $ cartodb-import test.csv # "config.json" will be used for credentials by default
    $ cartodb-import --url http://sig.pilote41.fr/urbanisme/aleas_inondation/aleas_sauldre_shp.zip
    

    Keywords

    none

    Install

    npm i cartodb

    DownloadsWeekly Downloads

    332

    Version

    0.5.1

    License

    BSD-3-Clause

    Last publish

    Collaborators

    • chriswhong
    • javisantana
    • nerik