This library abstracts calls to CARTO's SQL, Import, and Maps APIs.
NB! It is not official and not maintained. The version in NPM is outdated and does not work. If you want to use a bit updated version, use one directly from GH repo as:
"cartodb": "github:cartodb/cartodb-nodejs#master",
npm install github:cartodb/cartodb-nodejs#masterHere'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
});
var sql = new CartoDB.SQL({
user: {USERNAME},
api_key: {APIKEY}
});
Note: api_key is only required for a write query.
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 : CARTO 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);
});
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);
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!');
});
Pass in a config object with user and api_key
var namedMaps = new CartoDB.Maps.Named({
user: 'username',
api_key: 'yourreallylongcartodbapikey'
});
All methods create a promise, and you can listen for done and _error events.
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' }
namedMaps.update({
template: template
})
.on('done', function(res) {
console.log(res)
})
Response:
{ template_id: 'world_borders' }
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
namedMaps.list()
.on('done', function(res) {
console.log(res);
});
namedMaps.definition({
template_id: 'world_borders'
})
.on('done', function(res) {
console.log(res);
});
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.
--sqlFile string A file containing a SQL query (you can then omit -s).
-h, --help
$ 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
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
$ 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