Maps API v1

General Concepts

The following concepts are the same for every endpoint in the API except when it’s noted explicitly.

Auth

By default, users do not have access to private tables in CARTO. In order to instantiate a map from private table data an API Key is required. Additionally, an API Key is also required to use some of the API endpoints (e.g. to create a Named Map).

To execute an authorized request, api_key=YOURAPIKEY should be added to the request URL. The param can be also passed as POST param. Using HTTPS is mandatory when you are performing requests that include your api_key.

Errors

Errors are reported using standard HTTP codes and extended information encoded in JSON with this format:

1
2
3
4
5
{
  "errors": [
    "access forbidden to table TABLE"
  ]
}

If you use JSONP, the 200 HTTP code is always returned so the JavaScript client can receive errors from the JSON object.

CORS Support

All the endpoints, which might be accessed using a web browser, add CORS headers and allow OPTIONS method.

Map Tile Rendering

Map tiles create the graphical representation of your map in a web browser. The performance rendering of map tiles is dependent on the type of geospatial data model (raster or vector) that you are using.

• Raster: Generates map tiles based on a grid of pixels to represent your data. Each cell is a fixed size and contains values for particular map features. On the server-side, each request queries a dataset to retrieve data for each map tile. The grid size of map tiles can often lead to graphic quality issues.

• Vector: Generates map tiles based on pre-defined coordinates to represent your data, similar to how basemap image tiles are rendered. On the client-side, map tiles represent real-world geometries of a map. Depending on the coordinates, vertices are used to connect the data and display points, lines, or polygons for the map tiles.

Note: By default, CARTO uses vector graphics for map rendering. Please contact us if you need raster rendering enabled as part of your requirements.

Mapbox Vector Tiles (MVT)

Mapbox Vector Tiles (MVT) are map tiles that store geographic vector data on the client-side. Browser performance is fast since you can pan and zoom without having to query the server.

CARTO uses a Web Graphics Library (WebGL) to process MVT files. This is useful since WebGL’s are compatible with most web browsers, include support for multiple client-side mapping engines, and do not require additional information from the server; which makes it more efficient for rendering map tiles.

Tip: You can process MVT files with the ST_AsMVT PostGIS function with the Maps API Windshaft renderer.