The CARTO Maps API allows you to generate maps based on data hosted in your CARTO account.
The CARTO Maps API allows you to generate maps based on data hosted in your CARTO account.
This specification describes an extension for MapConfig 1.4.0 version.
This extension depends on Analyses extension. It extends MapConfig with a new attribute: dataviews.
It makes possible to get tabular data from analysis nodes: aggregated lists, aggregations, and histograms.
An aggregation is a list with aggregated results by a column and a given aggregation function.
Definition
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
// REQUIRED
// string, `type` the aggregation type
“type”: “aggregation”,
// REQUIRED
// object, `options` dataview params
“options”: {
// REQUIRED
// string, `column` column name to aggregate by
“column”: “country”,
// REQUIRED
// string, `aggregation` operation to perform
“aggregation”: “count”
// OPTIONAL
// string, `aggregationColumn` column value to aggregate
// This param is required when `aggregation` is different than "count"
“aggregationColumn”: “population”
}
}
Expected output
1
2
3
4
5
6
7
8
9
10
11
12
13
{
"type": "aggregation",
"categories": [
{
"category": "foo",
"value": 100
},
{
"category": "bar",
"value": 200
}
]
}
Histograms represent the data distribution for a column.
Definition
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
// REQUIRED
// string, `type` the histogram type
“type”: “histogram”,
// REQUIRED
// object, `options` dataview params
“options”: {
// REQUIRED
// string, `column` column name to aggregate by
“column”: “name”,
// OPTIONAL
// number, `bins` how many buckets the histogram should use
“bins”: 10
}
}
Expected output
1
2
3
4
5
{
"type": "histogram",
"bins": [{"bin": 0, "start": 2, "end": 2, "min": 2, "max": 2, "freq": 1}, null, null, {"bin": 3, "min": 40, "max": 44, "freq": 2}, null],
"width": 10
}
Formulas given a final value representing the whole dataset.
Definition
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
// REQUIRED
// string, `type` the formula type
“type”: “formula”,
// REQUIRED
// object, `options` dataview params
“options”: {
// REQUIRED
// string, `column` column name to aggregate by
“column”: “name”,
// REQUIRED
// string, `aggregation` operation to perform
“operation”: “count”
}
}
Operation must be: “min”, “max”, “count”, “avg”, or “sum”.
Result
1
2
3
4
5
6
{
"type": "formula",
"operation": "count",
"result": 1000,
"nulls": 0
}
The new dataviews attribute must be a dictionary of dataviews.
An analysis node id can be referenced from dataviews to consume its output query.
The layer consuming the output must reference it with the following option:
1
2
3
4
5
6
7
8
9
{
// REQUIRED
// object, `source` as in the future we might want to have other source options
"source": {
// REQUIRED
// string, `id` the analysis node identifier
"id": "HEAD"
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
{
"version": "1.4.0",
"layers": [
{
"type": "cartodb",
"options": {
"source": {
"id": "HEAD"
},
"cartocss": "...",
"cartocss_version": "2.3.0"
}
}
],
"dataviews" {
"basic_histogram": {
"source": {
"id": "HEAD"
},
"type": "histogram",
"options": {
"column": "pop_max"
}
}
},
"analyses": [
{
"id": "HEAD",
"type": "source",
"params": {
"query": "select * from your_table"
}
}
]
}
Camshaft’s analyses expose a filtering capability and aggregation and histogram dataviews get them for free with
this extension. Filters are available with the very dataview id, so if you have a “basic_histogram” histogram dataview
you can filter with a range filter with “basic_histogram” name.
Allows to remove results that are not contained within a set of elements.
Initially this filter can be applied to a numeric or text columns.
Params
1
2
3
4
{
“accept”: [“Spain”, “Germany”]
“reject”: [“Japan”]
}
Allows to remove results that don’t satisfy numeric min and max values. Filter is applied to a numeric column.
Params
1
2
3
4
{
“min”: 0,
“max”: 1000
}
Filters must be applied at map instantiation time.
With :mapconfig as a valid MapConfig and with :filters (a valid JSON) as:
GET /api/v1/map?config=:mapconfig&filters=:filters
POST /api/v1/map?filters=:filters
with BODY=:mapconfig
If in the future we need to support a bigger filters param and it doesn’t fit in the query string, we might solve it by accepting:
POST /api/v1/map
with BODY={“config”: :mapconfig, “filters”: :filters}
Assume :params (a valid JSON) as named maps params, like in: {“color”: “red”}
GET /api/v1/named/:name/jsonp?config=:params&filters=:filters&callback=cb
POST /api/v1/named/:name?filters=:filters
with BODY=:params
If, again, in the future we need to support a bigger filters param that doesn’t fit in the query string, we might solve it by accepting:
POST /api/v1/named/:name
with BODY={“config”: :params, “filters”: :filters}
A bounding box filter allows to remove results that don’t satisfy a geospatial range.
The bounding box special filter is available per dataview and there is no need to create a bounding box definition as it’s always possible to apply a bbox filter per dataview.
A dataview can get its result filtered by bounding box by sending a bbox param in the query string,
param must be in the form west,south,east,north.
So applying a bbox filter to a dataview looks like: GET /api/v1/map/:layergroupid/dataview/:dataview_name?bbox=-90,-45,90,45