Skip to content

Instantly share code, notes, and snippets.

@juanignaciosl

juanignaciosl/visualization_rest_api.md

Last active December 30, 2015 10:40
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save juanignaciosl/46a6520efbbe15681b62 to your computer and use it in GitHub Desktop.
Save juanignaciosl/46a6520efbbe15681b62 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
visualization_rest_api.md

Creating and modifying a visualization with CartoDB REST API

Fields in the following examples:

  • API_KEY: user API Key. You can get at the Dashboard: top-right avatar menu --> Your account --> API Keys.
  • CARTOCSS: CartoCSS for the layer.
  • COORDS: coordinates (latitude, longitude). Example: [5.453680224345835, -15.048828125].
  • FILENAME: path to your file.
  • LAYER_ID: id of the layer.
  • MAP_ID: id of the visualization map.
  • PRIVACY: public, link or private.
  • ORDER_COLUMN: column of the table you want to use for sorting.
  • QUERY_STRING: text to search for.
  • TABLE: the table the layer is using.
  • SQL: sql query for the layer.
  • USERNAME: username.
  • VIS_TYPE: visualization type to search for, either table for datasets or derived for visualizations.
  • VISUALIZATION_ID: id of the visualization you want to modify.
  • ZOOM: zoom level (0-18).

## Importing a table

You can import files into CartoDB tables with the Import API. Here's an example, you can find more at Import API documentation:

curl -v -F file=@FILENAME "https://USERNAME.cartodb.com/api/v1/imports?api_key=API_KEY&create_vis=true"
curl -v -F file=@orders.csv "https://shopuser.cartodb.com/api/v1/imports?api_key=bff4e173aa13bbd761f74856d3d4a9067faa0970e&create_vis=true"

Previous example creates a new dataset named "orders" and a new visualization named "Untitled Map" (because of create_vis parameter).

## Modifying metadata

Getting the visualization id

In order to modify the visualization you need its id. You can get it at the browser URL opening the visualization at the dashboard.

If you want to get the id programatically, you can search for it with the following request:

curl 'https://USERNAME.cartodb.com/api/v1/viz/?tag_name=&q=QUERY_STRING&order=ORDER_COLUMN&types=VIS_TYPE&api_key=API_KEY'
curl 'https://shopuser.cartodb.com/api/v1/viz/?tag_name=&q=Orders&order=updated_at&types=derived&api_key=bff4e173aa13bbd761f74856d3d4a9067faa0970e'

That will return a JSON array with the matching visualizations and its data, including its id and map_id.

Setting the title

curl 'https://USERNAME.cartodb.com/api/v1/viz/VISUALIZATION_ID?api_key=API_KEY' -X PUT -d '{"id":"VISUALIZATION_ID","name":"NEW NAME"}'
curl 'https://shopuser.cartodb.com/api/v1/viz/6977d8aa-ae42-11e5-b70c-0ef7f98ade21?api_key=bff4e173aa13bbd761f74856d3d4a9067faa0970e' -X PUT -d '{"id":"6977d8aa-ae42-11e5-b70c-0ef7f98ade21","name":"Orders map"}'

Setting the description

curl 'https://USERNAME.cartodb.com/api/v1/viz/VISUALIZATION_ID?api_key=API_KEY' -X PUT -d '{"id":"VISUALIZATION_ID","description":"NEW DESCRIPTION"}'
curl 'https://shopuser.cartodb.com/api/v1/viz/6977d8aa-ae42-11e5-b70c-0ef7f98ade21?api_key=bff4e173aa13bbd761f74856d3d4a9067faa0970e' -X PUT -d '{"id":"6977d8aa-ae42-11e5-b70c-0ef7f98ade21","description":"Map with our latest orders"}'

### Setting the tags

curl 'https://USERNAME.cartodb.com/api/v1/viz/VISUALIZATION_ID?api_key=API_KEY' -X PUT -d '{"id":"VISUALIZATION_ID","tags":["TAG 1","TAG 2"]}'
curl 'https://shopuser.cartodb.com/api/v1/viz/6977d8aa-ae42-11e5-b70c-0ef7f98ade21?api_key=bff4e173aa13bbd761f74856d3d4a9067faa0970e' -X PUT -d '{"id":"6977d8aa-ae42-11e5-b70c-0ef7f98ade21","tags":["2015","sales"]}'

Setting the privacy

curl 'https://USERNAME.cartodb.com/api/v1/viz/VISUALIZATION_ID?api_key=API_KEY' -X PUT -d '{"id":"VISUALIZATION_ID","privacy":"PRIVACY"}'
curl 'https://shopuser.cartodb.com/api/v1/viz/6977d8aa-ae42-11e5-b70c-0ef7f98ade21?api_key=bff4e173aa13bbd761f74856d3d4a9067faa0970e' -X PUT -d '{"id":"6977d8aa-ae42-11e5-b70c-0ef7f98ade21","privacy":"link"}'

## Modifying the visualization

Getting the map id

A visualization has a map. Its id is in the visualization, and you can get it from the previous visualization search. If you already have the visualization id you can get it with the following request:

curl 'https://USERNAME.cartodb.com/api/v1/viz/VISUALIZATION_ID?api_key=API_KEY'
curl 'https://shopuser.cartodb.com/api/v1/viz/6977d8aa-ae42-11e5-b70c-0ef7f98ade21?api_key=bff4e173aa13bbd761f74856d3d4a9067faa0970e'

Setting the position of the map

You can change the position of the map in two ways: zoom + center, or view bounds.

Setting the position of the map with zoom + center

Set both zoom and center and set view_bounds_sw and view_bounds_ne to null so they can be recalculated.

curl 'https://USERNAME.cartodb.com/api/v1/maps/MAP_ID?api_key=API_KEY' -X PUT -d '{"id":"MAP_ID","view_bounds_ne":null,"view_bounds_sw":null,"zoom":ZOOM,"center":[COORDS]}' -H 'Content-Type: application/json'
curl 'https://shopuser.cartodb.com/api/v1/maps/ed0cb2cf-f638-4bf8-9943-7d44c16a50b5?api_key=bff4e173aa13bbd761f74856d3d4a9067faa0970e' -X PUT -d '{"id":"ed0cb2cf-f638-4bf8-9943-7d44c16a50b5","view_bounds_ne":null,"view_bounds_sw":null,"zoom":1,"center":[0,0]}' -H 'Content-Type: application/json'

Changing the position of the map with view bounds

Set both view_bounds_sw and view_bounds_ne. zoom and center are ignored

curl 'https://USERNAME.cartodb.com/api/v1/maps/MAP_ID?api_key=API_KEY' -X PUT -d '{"id":"MAP_ID","view_bounds_ne":COORDS,"view_bounds_sw":COORDS}' -H 'Content-Type: application/json'
curl 'https://shopuser.cartodb.com/api/v1/maps/ed0cb2cf-f638-4bf8-9943-7d44c16a50b5?api_key=bff4e173aa13bbd761f74856d3d4a9067faa0970e' -X PUT -d '{"id":"ed0cb2cf-f638-4bf8-9943-7d44c16a50b5","view_bounds_ne":[59.96043926902489, 50.732421875],"view_bounds_sw":[5.453680224345835, -15.048828125]}' -H 'Content-Type: application/json'

Setting the style

Getting the layer ids

curl 'https://USERNAME.cartodb.com/api/v1/maps/MAP_ID/layers?api_key=API_KEY'
curl 'https://shopuser.cartodb.com/api/v1/maps/ed0cb2cf-f638-4bf8-9943-7d44c16a50b5/layers?api_key=bff4e173aa13bbd761f74856d3d4a9067faa0970e'

This request returns an array of layers of the map. For a simple, 1 layer map with labels on top, it returns three: a order: 0 tiled layer for the basemap, a order: 1 cartodb layer for the data, and a order: 2 tiled layer for the labels. You can check the type with the kind attribute and get the relevant one with order attribute.

Setting the style of a layer

First get the current layer metadata, change the style you want, and then PUT the changes. Example:

Getting the current layer metadata

curl 'https://USERNAME.cartodb.com/api/v1/maps/MAP_ID/layers/LAYER_ID?api_key=API_KEY'
curl 'https://shopuser.cartodb.com/api/v1/maps/ed0cb2cf-f638-4bf8-9943-7d44c16a50b5/layers/fd7d1156-8ecf-4f36-a332-8cc609e63656?api_key=bff4e173aa13bbd761f74856d3d4a9067faa0970e'

This returns the full layer JSON:

{"options":{"attribution":"CartoDB <a href=\"http://cartodb.com/attributions\" target=\"_blank\">attribution</a>","type":"CartoDB","active":true,"query":null,"opacity":0.99,"interactivity":"cartodb_id","interaction":true,"debug":false,"tiler_domain":"cartodb.com","tiler_port":"80","tiler_protocol":"http","sql_api_domain":"cartodb.com","sql_api_port":"80","sql_api_protocol":"http","extra_params":{"cache_buster":1451465207585},"cdn_url":null,"maxZoom":28,"style_version":"2.1.1","table_name":"orders","user_name":"shopuser","tile_style":"/** simple visualization */\n\n#orders{\n  marker-fill-opacity: 0.9;\n  marker-line-color: #6B0FB2;\n  marker-line-width: 1;\n  marker-line-opacity: 1;\n  marker-placement: point;\n  marker-type: ellipse;\n  marker-width: 10;\n  marker-fill: #FF0000;\n  marker-allow-overlap: true;\n}","id":"fd7d1156-8ecf-4f36-a332-8cc609e63656","order":1,"use_server_style":true,"query_history":[],"stat_tag":"6977d8aa-ae42-11e5-b70c-0ef7f98ade21","maps_api_template":"https://{user}.cartodb.com:443","cartodb_logo":false,"no_cdn":false,"force_cors":true,"visible":true,"tile_style_custom":true,"query_wrapper":null,"query_generated":false,"wizard_properties":{"type":"polygon","properties":{"marker-width":10,"marker-fill":"#FF0000","marker-opacity":0.9,"marker-allow-overlap":true,"marker-placement":"point","marker-type":"ellipse","marker-line-width":1,"marker-line-color":"#FFF","marker-line-opacity":1,"marker-comp-op":"none","text-name":"None","text-face-name":"DejaVu Sans Book","text-size":10,"text-fill":"#000","text-halo-fill":"#FFF","text-halo-radius":1,"text-dy":-10,"text-allow-overlap":true,"text-placement-type":"dummy","text-label-position-tolerance":0,"text-placement":"point","geometry_type":"point"}},"legend":{"type":"none","show_title":false,"title":"","template":"","visible":true}},"kind":"carto","infowindow":{"fields":[],"template_name":"table/views/infowindow_light","template":"","alternative_names":{},"width":226,"maxHeight":180},"tooltip":{"fields":[],"template_name":"tooltip_light","template":"","alternative_names":{},"maxHeight":180},"id":"fd7d1156-8ecf-4f36-a332-8cc609e63656","order":1}

We can change marker-fill to #00FF00 green and PUT the change:

curl -X PUT -d '{"options":{"attribution":"CartoDB <a href=\"http://cartodb.com/attributions\" target=\"_blank\">attribution</a>","type":"CartoDB","active":true,"query":null,"opacity":0.99,"interactivity":"cartodb_id","interaction":true,"debug":false,"tiler_domain":"cartodb.com","tiler_port":"80","tiler_protocol":"http","sql_api_domain":"cartodb.com","sql_api_port":"80","sql_api_protocol":"http","extra_params":{"cache_buster":1451465207585},"cdn_url":null,"maxZoom":28,"style_version":"2.1.1","table_name":"orders","user_name":"shopuser","tile_style":"/** simple visualization */\n\n#orders{\n  marker-fill-opacity: 0.9;\n  marker-line-color: #6B0FB2;\n  marker-line-width: 1;\n  marker-line-opacity: 1;\n  marker-placement: point;\n  marker-type: ellipse;\n  marker-width: 10;\n  marker-fill: #00FF00;\n  marker-allow-overlap: true;\n}","id":"fd7d1156-8ecf-4f36-a332-8cc609e63656","order":1,"use_server_style":true,"query_history":[],"stat_tag":"6977d8aa-ae42-11e5-b70c-0ef7f98ade21","maps_api_template":"https://{user}.cartodb.com:443","cartodb_logo":false,"no_cdn":false,"force_cors":true,"visible":true,"tile_style_custom":true,"query_wrapper":null,"query_generated":false,"wizard_properties":{"type":"polygon","properties":{"marker-width":10,"marker-fill":"#FF0000","marker-opacity":0.9,"marker-allow-overlap":true,"marker-placement":"point","marker-type":"ellipse","marker-line-width":1,"marker-line-color":"#FFF","marker-line-opacity":1,"marker-comp-op":"none","text-name":"None","text-face-name":"DejaVu Sans Book","text-size":10,"text-fill":"#000","text-halo-fill":"#FFF","text-halo-radius":1,"text-dy":-10,"text-allow-overlap":true,"text-placement-type":"dummy","text-label-position-tolerance":0,"text-placement":"point","geometry_type":"point"}},"legend":{"type":"none","show_title":false,"title":"","template":"","visible":true}},"kind":"carto","infowindow":{"fields":[],"template_name":"table/views/infowindow_light","template":"","alternative_names":{},"width":226,"maxHeight":180},"tooltip":{"fields":[],"template_name":"tooltip_light","template":"","alternative_names":{},"maxHeight":180},"id":"fd7d1156-8ecf-4f36-a332-8cc609e63656","order":1}' -H 'Content-Type: application/json' 'https://shopuser.cartodb.com/api/v1/maps/ed0cb2cf-f638-4bf8-9943-7d44c16a50b5/layers/fd7d1156-8ecf-4f36-a332-8cc609e63656?api_key=bff4e173aa13bbd761f74856d3d4a9067faa09'
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment