CartoDB

Using CartoDB

Getting started with CartoDB

CartoDB is a geospatial database on the cloud that allows for the storage and visualization of data on the web. Using CartoDB will allow you to quickly create map based visualizations. Here are a few ways you can use CartoDB.

• Upload, visualize, and manage your data using the The CartoDB dashboard.

• Quickly create and customize maps that you can embed or share via public URL using the map embedding tool.

• Analyze, and integrate data you store on CartoDB into your applications using the SQL API.

• For more advance integrations of CartoDB maps on your website or application, use the Maps API

A few more reasons to use CartoDB

Analyze data

CartoDB gives you access to a PostGIS enabled PostgreSQL database containing your data. These geospatially enabled databases not only give you complete control of your data, but a suite of tools with limitless potential for analyzing your data. PostgresSQL and PostGIS are both open-source projects developed independently of CartoDB, their documentation pages are very helpful for unleashing CartoDB’s full potential. Also, be sure to check out some of our Galleries for inspiration!

Develop applications

CartoDB provides a powerful data management and geospatial analysis backend for your application. Among many features, CartoDB includes a Maps API that provides projected map tiles for you to create fast data visualization, and the SQL API that allows you to query your data, or through secure connection, write new data to your CartoDB tables.

Secure data storage

We provide secure and safe storage of your data. In all accounts, your data is yours to write and modify (take a look at authentication for further info). In all subscription level accounts, we also provide the ability to host private tables, where you will be the only person able to read the data. On top of read and write security, CartoDB offers data backup services at every level of hosting. That means your data will be there every time you log-in, no question.

Scalable distribution

Using CDN technology, maps created with CartoDB get distributed over a network of edge locations all around the world. That ensure maximum speed and reliability when handling large amounts of request. CartoDB works with 10 views per day or 10 million views per day.

Scalable storage

You can’t always be certain the scale of your project before you get started. CartoDB storage is easily scalable, allowing you to upgrade your account seamlessly at any point in time. Check-out the pricing page to see the difference in CartoDB accounts and see which ones fits your needs right now.

CartoDB is open source

The team behind CartoDB have a strong commitment to Open Source. Even before the development of CartoDB, we have used, contributed to, and created many open-source projects. With CartoDB, we have continued that tradition. We have built the tool on a stack of some of our favorite open-source technologies, including, PostgreSQL, PostGIS, Mapnik, and our very own WindShaft. CartoDB is no different, you can find the code in our git repository.

So why use our service? With CartoDB comes a cadre of information technology specialists and developers that help keep your data running, secure, and available in the cloud. We also offer seamless account upgrades and always keep your data hosted on the latest CartoDB release.

Quotas and billing

Several tiers of usage are available for CartoDB, ranging from a free account to a fully dedicated instance. The difference between these accounts is in their physical storage size, memory size, and several CartoDB features. You can find full details on these differences over on the pricing page.

In cases where there is a lot of map views, CartoDB will not automatically close your service, so you can be sure there will be no cuts on service. On the other hand the different plans have different amount of allocated map views. Check out the terms of service for more info. If your website/application using CartoDB consistently passes those limits you might get charged for extra usage.

Upgrading your account

A user's storage space is limited based on account type. Potentially two types of storage are calculated. First, the total physical storage space of your tables. This includes all columns and rows in your table. Second, your total number of tables. If your are limited by either of these, please upgrade your account!

Changing your account type is easy!

• Go to your CartoDB settings page.

• In the upper right of the settings page, you will see a big button that says, Upgrade your server, click it.

• Select the account size you want.

• Fill in your contact and billing information and review our Terms of Service.

• Submit your request!

As soon as your request be processed successfully we will upgrade your account and notify you via email. If you want to go dedicated, email us.

Managing your tables

Management of data in your CartoDB account starts with the Dashboard. The Dashboard allows you to see all tables you have created, delete old ones, and create new ones. It also gives you access to important account information such as how much of your quotas are being used.

Creating tables

You can create new tables a couple of ways. Start by clicking the Create a new table button, and then selecting one of the methods below.

• Create an empty table. If you plan to insert data by hand or programmatically you can create a new blank table with the default CartoDB columns and indexes in place.

• Upload a file. CartoDB offers drag and drop functionality, meaning that you can drag any supported file type from your desktop directly into your browser. Following upload, you will be redirected to your new table.

• Import from a URL. If you provide a URL, CartoDB will handle all download and processing of the file without your bandwidth being affected at all.

Formats accepted

CartoDB supports a growing number of data-types and file formats. We encourage you to compress all your files before importing them, supported compression and archiving formats are currently .ZIP and .GZ (also .TAR.GZ and .TGZ). For all other file formats, see the table below.

.CSV	Comma-separated values and Tab delimited file
.ZIP *	ESRI Shape File
.KML, .KMZ	Keyhole Markup Language
.XLS, .XLSX	Excel Spreadsheet
.GEOJSON, .JSON	GeoJSON
.GPX	GPS eXchange Format
.OSM, .BZ2	Open Street Map
.ODS	OpenDocument Spreadsheet
.ZIP	GeoTIFF

* ESRI Shape Files require at least three separate files. CartoDB requires that you include all of the files in a single compressed archive.

Errors

Three main categories of errors can be encountered in CartoDB: import errors, SQL errors, and CartoCSS errors. Errors are reported to you any time we do not have an automated solution. If the error indicates something you can fix and retry go for it! Otherwise, please feel free to report your error to our support team.

Tagging tables

As the number of tables in your account grows, one of the most useful ways to keep track of them is through the use of tags. You can add tags to any table in your account. You can use tags to filter tables using the Browse By Tags feature in the right column of your Dashboard.

Managing your data

After importing your data, you will be redirected to a table view of your data. From here, you can change the name of your table (click on the current name), add tags to the table, delete it, or use a host of advanced tools. Sometimes when looking at your table, there will be too many columns for the width of your browser. In these cases you can navigate right and left across columns by clicking the right and left arrows located to the upper right of the data table. You can also switch back and forth between your Table tab and your Map tab (detailed below).

Create columns and rows

Adding columns and rows is easy using the corresponding Add column and Add row buttons found at the very bottom right side of your table. If you click, Add column, you will be asked for the name and data-type for your new column. After clicking Create it will be added to your table. If you click Add row, a new empty row will be added to the bottom of the table.

Changing data-type

In some cases, you will want to change the data-type of a column. For example, CSV data is often imported as string characters when in fact the column contains only numbers. To change the data-type of a column, click the current data-type (found directly under the column name). Next, select the data-type you wish to change the column to. Be careful, if you change a column from Strings to Numbers, values that cannot be converted will be lost! This goes for any conversion.

Edit data

Any cell in your table can be edited on the fly by double-clicking that cell. Remember, that columns have data-types, so if your column is a number column you will not be able to add the value “hello” successfully.

Filter by row values

You can filter rows by a value by clicking the down-arrow beside the column name, and then clicking Filter by this column in the menu. Next, you will be able to enter a value to filter your rows with. Enter the value you are looking for, click Apply query and the results will be shown in your table.

Creating and styling your map

To view your data on a map, click the Map tab in the upper left under the table name and tags. The first time you view your data on the map, CartoDB will zoom the map to the extents of your data and put some default styles onto it. If nothing shows up here, it might be because you don’t have any geospatial information in your table. Double-check that the column the_geom, in your table has some date.

Basic styling controls

CartoDB gives you full control of the style and presentation of your data. Some of the basic controls include coloring and line-width controls. You can access these by clicking the drop down arrow to the right of Visualization type in the upper center of your map.

Infowindows

The default info windows generated by CartoDB contain all the columns of your table. You can change the defaults by clicking the drop down arrow beside Infowindow customization at the top of your map. From here, click Custom, and then turn off or on any of the features you want included in your infowindow.

Thematic mapping

Thematic mapping is the ability to quickly summarize your data on the map. CartoDB allows you to visualize your data using a handful of thematic mapping techniques by selecting them on your map. These include some techniques such as, choropleths for points and bubble maps for points. Thematic maps are semi-dependent on the type of data you are trying to visualize (point, polygon, and linestring) and CartoDB makes those choices easy for you. From any map of your data, click the down arrow to the right of Visualization type in the upper center of your map to access the thematic mapping menu. From here, based on your data-type, you will be presented different ways to map your data based on values associated with each feature.

• Bubble maps
  This scales the radius of points on the map based on a secondary numeric value from a column in your table that you choose. Parameters you can change include the maximum and minimum size of your bubbles and the color schemes.

• Numeric choropleth
  This changes the color of each feature based on a secondary numeric value from a column in your table that you choose. Parameters you can change include the color ramp and number of bins your data will be fit into.

Classifying data

When you create a thematic map in CartoDB, your data needs to be divided into several groups with starting points and ending points. To do this, CartoDB enables several methods. There are different times to use each method based on your data and your visualization requirements. While we provide an overview here, please explore these concepts further if you aim to do rigorous data visualization.

• Jenks natural breaks
  The Jenks method aims to increase the standard deviation between each group of data, while decreasing the standard deviation within each group. In other words, it tries to make each group more similar to itself and very different from each of the others. The Jenks method does this by shuffling data across each group until it detects an optimization.

• Equal interval breaks
  This method is probably the easiest to conceptualize, it simply takes the range of your data and divides the total range into equally sized subranges for your desired number of groups.

• Quantile breaks
  The Quantile method creates groups with an equal number of discrete units for each group. The discrete units are gathered from the distinct possible values from your data.

• Heads/Tails breaks This method can be very powerful for data with a long-tail distribution. The Heads/Tails method will create a break-point at the mean of your data, remove all data below the break-point and create the next break-point from the data above the first break-point. It will repeat the process until either only a single value is left above the break-point or it reaches the desired number of breaks.
  

The power of CartoCSS language

You are not limited to just the styling methods above; CartoDB gives you access to a powerful styling language called Carto. CartoCSS is a CSS-like language for styling maps, and allows you to style all your data in a very dynamic way. It lets you assign styles to all features in your dataset or style features based on values of rows using conditional parameters such as, equal to, less than, and more than. Combined with the power of SQL statements, you can use CartoDB to make advanced data visualizations. Start styling your maps by clicking the Carto button at the lower right corner of your map.

Don't be afraid to experiment! The backward and forward arrows in the lower left of the CartoCSS window allow you to undo and redo your changes. If you make a mistake, simply hit the undo button until your CartoCSS is back to a working state.

CartoCSS samples

Running queries

CartoDB is powered by a spatially enabled relational database. SQL is how you can really access the full power of the database to analyze, process, and retrieve your data. While the default methods of CartoDB can get you very far, using SQL will advance your project a lot. Much of the SQL you will want to run is not directly geospatial in nature, things like MIN, MAX, COUNT, or DISTINCT. All of those are part of the core database technology, PostgreSQL. See the PostgreSQL documentation to learn more about what is possible and how.

For queries where you wish to perform geospatial analysis on your data you will be accessing methods implemented by a library called PostGIS. PostGIS enables to perform queries using methods like intersections, unions, and distances. PostGIS is implemented seamlessly within the same SQL query structure of PostgreSQL, so see the PostGIS documentation for details about what is possible and how to do it using this library.

SQL in CartoDB

To perform an SQL query in CartoDB, first load the table from your Dashboard. Once you have opened your table, in the lower right corner of your table you will see a button SQL, click it. This brings up a small text input window, from here you can enter any SQL query for your table and run it.

The default query in the SQL window simply selects all columns and all records from your table. After you have entered a new query, click Apply query. When the query has finished executing, the result will be retrieved and displayed in your table. Now you can view and validate your result. If you want to return to the full table at any point, click the Clear view link, at the top of the screen beside the table name.

Visualize the results on the map

To visualize the results of your query on the map, just click the Map tab at the top of the screen. While viewing the map you can also perform new or update your current SQL statement by clicking the SQL button in the lower-right of the screen. If you leave your table and return to it in your browser, your SQL statement is not saved and you are returned to the full data view. One thing to remember is that, to map your data you need to include geometries in your result. CartoDB relies on a column named the_geom_webmercator, a reprojected version of your geometries used to view data on Google Maps. To see your data in the Map tab, CartoDB requires that the_geom_webmercator column is in your results.

Modifying data

Though modifying CartoDB through the user interface is easy, CartoDB also makes it easy for you to manage changes to your data using SQL. To do so, use the INSERT, UPDATE, and DELETE commands available in PostgreSQL. Remember, these commands are only available to authenticated users, so even in tables you share publicly, only you and your collaborators will be able to modify the data.

Merge data

Whether you are using data from public repositories or your own datasets, sometimes it is nice to be able to join two tables together. Of course you can always do it on your own using SQL, but CartoDB makes it very easy to do with the merging tool for tables. The most basic way to join two tables is by a shared unique value, we call this a Regular Join. For example, country ISO codes can often be used to merge, say, the_geom from one table and population count from a second. Regular Joins are also very useful for things like, shared IDs, country names, or dates.

Merge by Regular Join

Regular Joins are useful if you have two datasets that share a common value in rows. For example, country level datasets often contain an ISO code for each row. If you have two of these datasets and want to join all or some of their values into a single table, this option is for you. Simply,

• From the table you have created, click options in the upper right corner.

• Select Merge tables.

• Click the radio Regular join.

• In the left-hand menu is your first table, you can toggle on or off the columns you want to include in the join

• The right-hand menu is for loading your second table. Click the drop down menu and select, or begin typing, the name of your second table.

• In the second table, toggle on or off the columns from the second table you want to join to the first.

• Use the radio to the left of column names in both the first table and the second. Use the radio to select the column in the first table that corresponds to a value in the second table. Do the same for the correct column name in the second table menu.

• Finally, hit Next, enter your new table name, and wait for the table to be processed.

Merge by Spatial Join

Table merging is an area we are developing actively, in the near future we will release a Spatial Join method, check back soon!

Export data

After you have created, updated, or deleted data from your CartoDB tables, you may want to export them for sharing or use offline. We make that easy for you by providing one-click data export.

• From any table you have created, click Options in the upper right corner.

• Select Export.

• From there, you should see a menu of export formats that CartoDB supports, including Comma separated (CSV), KML, ESRI Shape Files (SHP), and SQL.

• Click the format you would like to download.

Download by URL

There is a pro-tip for accessing downloads directly using your table URL. You can make use of the SQL API to run any query and ask for the results to be retrieved in different formats. For example:

http://{your_account_name}.cartodb.com/api/v2/sql?format=csv&q=select+*+from+tm_world_borders_sim

Share your map

All CartoDB accounts (except the free ones) allow you to make private tables. Private tables can only be viewed by an authenticated user on your account. Private tables can not be shared until you make them public. Making a table public means that your table is publicly available by URL. To do so, change your table visibility by clicking the button Private beside the table name.

Sharing a map

Sharing a map in CartoDB is easy and lets you make the most out of your data. To share your map, click the button Share this map beside the Map tab when looking at your table or map. Next, you will have a menu of options for how you can share your map.

• Direct Link.
  Allows you to pass a URL to collaborator or share it online. This will take viewers to a fullscreen map of your data.

• HTML Embed Code.
  Gives you an embeddable iFrame for your map, useful for putting interactive maps of your data in your website or blog. Below is an example embedded map showing election results in New Hampshire.

Both the direct link and embedded maps run live, directly off of your data. After sharing either of these, changes you make to your data will be visible on your maps.

Advanced functionality

Geocoding data

Sometimes the data you upload to CartoDB contains latitude and longitude fields that we were unable to detect automatically. In these cases, you will want to turn the fields you know represent latitude and longitude into point geometries.

Other times data you want to use in CartoDB does not contain geospatial data at all, but instead contains textual descriptions of places through a process called georeferencing.

CartoDB allows you to quickly and effortless turn either lat/lon fields or textual descriptions into point geometries. Next to the column you wish to georeference with, click the down arrow and select Georeference with. Next, you can select the fist option This is a lat/lon column, or the second one Create an address column. With the second option, you can combine one or more columns to describe the location of a record. The following example would combine three columns, town, state, and country into a single comma-delimited string that would be searched for corresponding lat/long.

Duplicate table

There may be times when you want to create a copy of your table. It might be because you want to work on a copy while keeping one set of your data untouched, or possibly it is because you need to develop the data in two different ways. When viewing your table, click the Advanced menu and select Duplicate table as.

Query as a table

Similar to Duplicate table, we provide a method called Query as a table, which allows you to perform an SQL query and store the results in a new table. To use this method, perform your SQL query on your CartoDB table. Double check that the result contains all the data you want in your final table, and click Query to a table in the advanced menu. Be sure to include the_geom column in your query if you want to have the geospatial data available in the new table.

Creating indexes

Adding indexes to your table can greatly improve the speed of your queries. We encourage you to look at the non-spatial indexing methods available in PostgreSQL as well as some spatial indexes that are available with PostGIS. CartoDB creates two indexes on your data automatically, one is a spatial index on the_geom column of every table and the second is a unique index on the cartodb_id column of every table.

General settings

You can edit your general account settings through the settings page of your dashboard. To do so, from your Dashboard, click the settings link in the upper right corner. This will take you to your settings page. From here you can see and upgrade your account size, edit account details, or delete your account.

Error codes and solutions

Importer errors

We try to predict and provide solutions for as many problems as we can, but that still leaves some cases where your CartoDB import is not going to work. For all these cases, we try to categorize your error and report the full error back to you at time of import. In those cases where you are not able to resolve the issue yourself, please give us the full description on our support platform

Here we provide a set of errors and some common solutions.

1000	File I/O error
1002	Unsupported file type - Check our list of supported files. see if you can convert your file to one of these file types.
1003	Decompression error - Try decompressing and regenerating your compressed file on your own computer. if that fails, find the original file and make a new compressed version of it.
1004	File encoding error - Sometimes we have difficulty with non UTF-8 files, try converting your file to UTF-8. You can do this in Excel by exporting your data as Unicode Text.
2000	File conversion errors.
3000	Geometry error.
3004	Unable to read SHP file - Try opening your SHP file in a local program such as QGIS. Does it open and display correctly? If so, try exporting it as a new SHP file and uploading to CartoDB.
3005	SHP to PGSQL error.
3100	Projection error - CartoDB supports many projection, but sometimes your file will have one we don't recognize. In these cases, please try reprojecting your file in QGIS or ArcGIS first. Or if you want to use this projection many times, submit a query to the support pages about getting it supported.
3101	Unsupported or missing projection - see 3100 above.
3102	Unable to force geometry to 2-dimensions.
3200	Unsupported geometry type.
3201	Geometry Collection not supported - Geometry Collections are not supported in CartoDB. In most cases we can deal with these during import, except with KML and GeoJSON import. In those cases, an intermediate step during import will fail if given geometry collections. To avoid this, try to export your data from the source in another format.
4000	Raster errors.
4001	Raster import error.
5000	Database import error.
5001	Empty table- If you upload a file that results in an empty table, we assume there was an error. If this in fact was not an error, please just use the user interface or send an SQL command to create a table. If it was in fact an error, check that your file is formatted correctly and that it contains data.
5002	Reserved column names - Try changing the name of your column to a new name. Often you can add an underscore, "_", to the beginning of the column name to make it work.
6000	OSM data import error.
8000	CartoDB account error.
8001	Over account storage limit - please upgrade, The file you tried to upload is putting you over your storage quota. You can upgrade your account easily using your account settings page to make your file work.
8002	Over account table limit - please upgrade, The file you tried to upload is putting you over your table quota. You can upgrade your account easily using your account settings page to make your file work. Alternatively, you may be able to delete some unused tables to make room.
9999	Unknown, Please report your error to support.cartodb.com so we can figure it out!

SQL errors

When executing SQL either in the user interface or through the SQL API, you may encounter errors. We report back to you the full error provided by PostgreSQL. One of the easiest ways to figure out what is going on is to search for your error on Google to find out what it means.

CartoCSS errors

CartoCSS styling is generally very simple, but still it can be easy to include typos or forget quotations. In cases when you are editing CartoCSS through the user interface, errors are reported back the the CartoCSS input window. From there, it is typically not too difficult to figure out what is going on. More often than not, make sure you have ended your lines with semi-colons, use quotes when needed, and closed all your brackets and braces.