Change highlighting to ```
This commit is contained in:
parent
c636a820d5
commit
10b1081960
196
docs/Map-API.md
196
docs/Map-API.md
@ -16,7 +16,7 @@ You can create two types of maps with the Maps API:
|
||||
|
||||
Here is an example of how to create an anonymous map with JavaScript:
|
||||
|
||||
{% highlight javascript %}
|
||||
```javascript
|
||||
var mapconfig = {
|
||||
"version": "1.0.1",
|
||||
"layers": [{
|
||||
@ -41,14 +41,14 @@ $.ajax({
|
||||
console.log(templateUrl);
|
||||
}
|
||||
})
|
||||
{% endhighlight %}
|
||||
```
|
||||
|
||||
### Named maps
|
||||
|
||||
Let's create a named map using some private tables in a CartoDB account.
|
||||
The following API call creates a map of European countries that have a white fill color:
|
||||
|
||||
{% highlight javascript %}
|
||||
```javascript
|
||||
// mapconfig.json
|
||||
{
|
||||
"version": "0.0.1",
|
||||
@ -67,38 +67,38 @@ The following API call creates a map of European countries that have a white fil
|
||||
}]
|
||||
}
|
||||
}
|
||||
{% endhighlight %}
|
||||
```
|
||||
|
||||
The map config needs to be sent to CartoDB's Map API using an authenticated call. Here we use a command line tool called `curl`. For more info about this tool see [this blog post](http://quickleft.com/blog/command-line-tutorials-curl) or type ``man curl`` in bash. Using `curl` the call would look like:
|
||||
|
||||
<div class="code-title notitle code-request"></div>
|
||||
{% highlight bash %}
|
||||
```bash
|
||||
curl 'https://{account}.cartodb.com/api/v1/map/named?api_key=APIKEY' -H 'Content-Type: application/json' -d @mapconfig.json
|
||||
{% endhighlight %}
|
||||
```
|
||||
|
||||
To get the `URL` to fetch the tiles you need to instantiate the map, where `template_id` is the template name from the previous response.
|
||||
|
||||
<div class="code-title notitle code-request"></div>
|
||||
{% highlight bash %}
|
||||
```bash
|
||||
curl -X POST 'http://{account}.cartodb.com/api/v1/map/named/:template_id' -H 'Content-Type: application/json'
|
||||
{% endhighlight %}
|
||||
```
|
||||
|
||||
The response will return JSON with properties for the `layergroupid` and the timestamp (`last_updated`) of the last data modification.
|
||||
|
||||
Here is an example response:
|
||||
|
||||
{% highlight javascript %}
|
||||
```javascript
|
||||
{
|
||||
"layergroupid": "c01a54877c62831bb51720263f91fb33:0",
|
||||
"last_updated": "1970-01-01T00:00:00.000Z"
|
||||
}
|
||||
{% endhighlight %}
|
||||
```
|
||||
|
||||
You can use the `layergroupid` to instantiate a URL template for accessing tiles on the client. Here we use the `layergroupid` from the example response above in this URL template:
|
||||
|
||||
{% highlight bash %}
|
||||
```bash
|
||||
http://documentation.cartodb.com/api/v1/map/c01a54877c62831bb51720263f91fb33:0/{z}/{x}/{y}.png
|
||||
{% endhighlight %}
|
||||
```
|
||||
|
||||
## General Concepts
|
||||
|
||||
@ -114,13 +114,13 @@ To execute an authorized request, api_key=YOURAPIKEY should be added to the requ
|
||||
|
||||
Errors are reported using standard HTTP codes and extended information encoded in JSON with this format:
|
||||
|
||||
{% highlight javascript %}
|
||||
```javascript
|
||||
{
|
||||
"errors": [
|
||||
"access forbidden to table TABLE"
|
||||
]
|
||||
}
|
||||
{% endhighlight %}
|
||||
```
|
||||
|
||||
If you use JSONP, the 200 HTTP code is always returned so the JavaScript client can receive errors from the JSON object.
|
||||
|
||||
@ -137,13 +137,13 @@ Anonymous maps allows you to instantiate a map given SQL and CartoCSS. It also a
|
||||
#### Definition
|
||||
|
||||
<div class="code-title notitle code-request"></div>
|
||||
{% highlight html %}
|
||||
```html
|
||||
POST /api/v1/map
|
||||
{% endhighlight %}
|
||||
```
|
||||
|
||||
#### Params
|
||||
|
||||
{% highlight javascript %}
|
||||
```javascript
|
||||
{
|
||||
"version": "1.0.1",
|
||||
"layers": [{
|
||||
@ -156,7 +156,7 @@ POST /api/v1/map
|
||||
}
|
||||
}]
|
||||
}
|
||||
{% endhighlight %}
|
||||
```
|
||||
|
||||
Should be a [Mapconfig](https://github.com/CartoDB/Windshaft/blob/0.19.1/doc/MapConfig-1.1.0.md).
|
||||
|
||||
@ -167,9 +167,9 @@ The response includes:
|
||||
- **layergroupid**
|
||||
The ID for that map, used to compose the URL for the tiles. The final URL is:
|
||||
|
||||
{% highlight html %}
|
||||
```html
|
||||
http://{account}.cartodb.com/api/v1/map/:layergroupid/{z}/{x}/{y}.png
|
||||
{% endhighlight %}
|
||||
```
|
||||
|
||||
- **updated_at**
|
||||
The ISO date of the last time the data involved in the query was updated.
|
||||
@ -183,12 +183,12 @@ The response includes:
|
||||
#### Example
|
||||
|
||||
<div class="code-title code-request with-result">REQUEST</div>
|
||||
{% highlight bash %}
|
||||
```bash
|
||||
curl 'http://documentation.cartodb.com/api/v1/map' -H 'Content-Type: application/json' -d @mapconfig.json
|
||||
{% endhighlight %}
|
||||
```
|
||||
|
||||
<div class="code-title">RESPONSE</div>
|
||||
{% highlight javascript %}
|
||||
```javascript
|
||||
{
|
||||
"layergroupid":"c01a54877c62831bb51720263f91fb33:0",
|
||||
"last_updated":"1970-01-01T00:00:00.000Z"
|
||||
@ -197,31 +197,31 @@ curl 'http://documentation.cartodb.com/api/v1/map' -H 'Content-Type: application
|
||||
"https": "https://cdb.com"
|
||||
}
|
||||
}
|
||||
{% endhighlight %}
|
||||
```
|
||||
|
||||
The tiles can be accessed using:
|
||||
|
||||
{% highlight bash %}
|
||||
```bash
|
||||
http://documentation.cartodb.com/api/v1/map/c01a54877c62831bb51720263f91fb33:0/{z}/{x}/{y}.png
|
||||
{% endhighlight %}
|
||||
```
|
||||
|
||||
For UTF grid tiles:
|
||||
|
||||
{% highlight bash %}
|
||||
```bash
|
||||
http://documentation.cartodb.com/api/v1/map/c01a54877c62831bb51720263f91fb33:0/:layer/{z}/{x}/{y}.grid.json
|
||||
{% endhighlight %}
|
||||
```
|
||||
|
||||
For attributes defined in `attributes` section:
|
||||
|
||||
{% highlight bash %}
|
||||
```bash
|
||||
http://documentation.cartodb.com/api/v1/map/c01a54877c62831bb51720263f91fb33:0/:layer/attributes/:feature_id
|
||||
{% endhighlight %}
|
||||
```
|
||||
|
||||
Which returns JSON with the attributes defined, like:
|
||||
|
||||
{% highlight javascript %}
|
||||
```javascript
|
||||
{ c: 1, d: 2 }
|
||||
{% endhighlight %}
|
||||
```
|
||||
|
||||
Notice UTF Grid and attributes endpoints need an intenger parameter, ``layer``. That number is the 0-based index of the layer inside the mapconfig. So in this case 0 returns the UTF grid tiles/attributes for layer 0, the only layer in the example mapconfig. If a second layer was available it could be returned with 1, a third layer with 2, etc.
|
||||
|
||||
@ -232,9 +232,9 @@ The JSONP endpoint is provided in order to allow web browsers access which don't
|
||||
#### Definition
|
||||
|
||||
<div class="code-title notitle code-request"></div>
|
||||
{% highlight bash %}
|
||||
```bash
|
||||
GET /api/v1/map?callback=method
|
||||
{% endhighlight %}
|
||||
```
|
||||
|
||||
#### Params
|
||||
|
||||
@ -253,15 +253,15 @@ GET /api/v1/map?callback=method
|
||||
#### Example
|
||||
|
||||
<div class="code-title code-request with-result">REQUEST</div>
|
||||
{% highlight bash %}
|
||||
```bash
|
||||
curl http://...
|
||||
{% endhighlight %}
|
||||
```
|
||||
|
||||
<div class="code-title">RESPONSE</div>
|
||||
{% highlight javascript %}
|
||||
```javascript
|
||||
{
|
||||
}
|
||||
{% endhighlight %}
|
||||
```
|
||||
|
||||
### Remove
|
||||
|
||||
@ -286,14 +286,14 @@ Template maps are persistent with no preset expiration. They can only be created
|
||||
#### Definition
|
||||
|
||||
<div class="code-title notitle code-request"></div>
|
||||
{% highlight html %}
|
||||
```html
|
||||
POST /api/v1/map/named
|
||||
{% endhighlight %}
|
||||
```
|
||||
|
||||
#### Params
|
||||
|
||||
<div class="code-title">template.json</div>
|
||||
{% highlight javascript %}
|
||||
```javascript
|
||||
{
|
||||
"version": "0.0.1",
|
||||
"name": "template_name",
|
||||
@ -328,7 +328,7 @@ POST /api/v1/map/named
|
||||
]
|
||||
}
|
||||
}
|
||||
{% endhighlight %}
|
||||
```
|
||||
|
||||
##### Arguments
|
||||
|
||||
@ -346,9 +346,9 @@ Valid placeholder names start with a letter and can only contain letters, number
|
||||
|
||||
##### Example
|
||||
|
||||
{% highlight javascript %}
|
||||
```javascript
|
||||
<%= my_color %>
|
||||
{% endhighlight %}
|
||||
```
|
||||
|
||||
The set of supported placeholders for a template will need to be explicitly defined with a specific type and default value for each.
|
||||
|
||||
@ -366,19 +366,19 @@ Placeholder default values will be used whenever new values are not provided as
|
||||
When using templates, be very careful about your selections as they can give broad access to your data if they are defined losely.
|
||||
|
||||
<div class="code-title code-request with-result">REQUEST</div>
|
||||
{% highlight html %}
|
||||
```html
|
||||
curl -X POST \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d @template.json \
|
||||
'https://documentation.cartodb.com/api/v1/map/named?api_key=APIKEY'
|
||||
{% endhighlight %}
|
||||
```
|
||||
|
||||
<div class="code-title">RESPONSE</div>
|
||||
{% highlight javascript %}
|
||||
```javascript
|
||||
{
|
||||
"templateid":"name",
|
||||
}
|
||||
{% endhighlight %}
|
||||
```
|
||||
|
||||
### Instantiate
|
||||
|
||||
@ -387,19 +387,19 @@ Instantiating a map allows you to get the information needed to fetch tiles. Tha
|
||||
#### Definition
|
||||
|
||||
<div class="code-title notitle code-request"></div>
|
||||
{% highlight html %}
|
||||
```html
|
||||
POST /api/v1/map/named/:template_name
|
||||
{% endhighlight %}
|
||||
```
|
||||
|
||||
#### Param
|
||||
|
||||
{% highlight javascript %}
|
||||
```javascript
|
||||
// params.json
|
||||
{
|
||||
color: "#ff0000",
|
||||
cartodb_id: 3
|
||||
}
|
||||
{% endhighlight %}
|
||||
```
|
||||
|
||||
The fields you pass as `params.json` depend on the variables allowed by the named map. If there are variables missing it will raise an error (HTTP 400)
|
||||
|
||||
@ -412,27 +412,27 @@ You can initialize a template map by passing all of the required parameters in a
|
||||
Valid credentials will be needed if required by the template.
|
||||
|
||||
<div class="code-title code-request with-result">REQUEST</div>
|
||||
{% highlight bash %}
|
||||
```bash
|
||||
curl -X POST \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d @params.json \
|
||||
'https://documentation.cartodb.com/api/v1/map/named/@template_name?auth_token=AUTH_TOKEN'
|
||||
{% endhighlight %}
|
||||
```
|
||||
|
||||
<div class="code-title">Response</div>
|
||||
{% highlight javascript %}
|
||||
```javascript
|
||||
{
|
||||
"layergroupid": "docs@fd2861af@c01a54877c62831bb51720263f91fb33:123456788",
|
||||
"last_updated": "2013-11-14T11:20:15.000Z"
|
||||
}
|
||||
{% endhighlight %}
|
||||
```
|
||||
|
||||
<div class="code-title">Error</div>
|
||||
{% highlight javascript %}
|
||||
```javascript
|
||||
{
|
||||
"error": "Some error string here"
|
||||
}
|
||||
{% endhighlight %}
|
||||
```
|
||||
|
||||
You can then use the `layergroupid` for fetching tiles and grids as you would normally (see anonymous map section). However, you'll need to show the `auth_token`, if required by the template.
|
||||
|
||||
@ -443,9 +443,9 @@ There is also a special endpoint to be able to initialize a map using JSONP (for
|
||||
#### Definition
|
||||
|
||||
<div class="code-title notitle code-request"></div>
|
||||
{% highlight bash %}
|
||||
```bash
|
||||
GET /api/v1/map/named/:template_name/jsonp
|
||||
{% endhighlight %}
|
||||
```
|
||||
|
||||
#### Params
|
||||
|
||||
@ -455,12 +455,12 @@ GET /api/v1/map/named/:template_name/jsonp
|
||||
- **callback:** JSON callback name
|
||||
|
||||
<div class="code-title code-request with-result">REQUEST</div>
|
||||
{% highlight bash %}
|
||||
```bash
|
||||
curl 'https://documentation.cartodb.com/api/v1/map/named/:template_name/jsonp?auth_token=AUTH_TOKEN&callback=callback&config=template_params_json'
|
||||
{% endhighlight %}
|
||||
```
|
||||
|
||||
<div class="code-title">RESPONSE</div>
|
||||
{% highlight javascript %}
|
||||
```javascript
|
||||
callback({
|
||||
"layergroupid":"c01a54877c62831bb51720263f91fb33:0",
|
||||
"last_updated":"1970-01-01T00:00:00.000Z"
|
||||
@ -469,32 +469,32 @@ callback({
|
||||
"https": "https://cdb.com"
|
||||
}
|
||||
})
|
||||
{% endhighlight %}
|
||||
```
|
||||
|
||||
This takes the `callback` function (required), `auth_token` if the template needs auth, and `config` which is the variable for the template (in cases where it has variables).
|
||||
|
||||
{% highlight javascript %}
|
||||
```javascript
|
||||
url += "config=" + encodeURIComponent(
|
||||
JSON.stringify({ color: 'red' });
|
||||
{% endhighlight %}
|
||||
```
|
||||
|
||||
The response is in this format:
|
||||
|
||||
{% highlight javascript %}
|
||||
```javascript
|
||||
callback({
|
||||
layergroupid: "dev@744bd0ed9b047f953fae673d56a47b4d:1390844463021.1401",
|
||||
last_updated: "2014-01-27T17:41:03.021Z"
|
||||
})
|
||||
{% endhighlight %}
|
||||
```
|
||||
|
||||
### Update
|
||||
|
||||
#### Definition
|
||||
|
||||
<div class="code-title notitle code-request"></div>
|
||||
{% highlight bash %}
|
||||
```bash
|
||||
PUT /api/v1/map/named/:template_name
|
||||
{% endhighlight %}
|
||||
```
|
||||
|
||||
#### Params
|
||||
|
||||
@ -511,29 +511,29 @@ Updating a named map removes all the named map instances so they need to be init
|
||||
#### Example
|
||||
|
||||
<div class="code-title code-request with-result">REQUEST</div>
|
||||
{% highlight bash %}
|
||||
```bash
|
||||
curl -X PUT \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d @template.json \
|
||||
'https://documentation.cartodb.com/api/v1/map/named/:template_name?api_key=APIKEY'
|
||||
{% endhighlight %}
|
||||
```
|
||||
|
||||
<div class="code-title">RESPONSE</div>
|
||||
{% highlight javascript %}
|
||||
```javascript
|
||||
{
|
||||
"template_id": "@template_name"
|
||||
}
|
||||
{% endhighlight %}
|
||||
```
|
||||
|
||||
If any template has the same name, it will be updated.
|
||||
|
||||
If a template with the same name does NOT exist, a 400 HTTP response is generated with an error in this format:
|
||||
|
||||
{% highlight javascript %}
|
||||
```javascript
|
||||
{
|
||||
"error": "error string here"
|
||||
}
|
||||
{% endhighlight %}
|
||||
```
|
||||
|
||||
Updating a template map will also remove all signatures from previously initialized maps.
|
||||
|
||||
@ -544,23 +544,23 @@ Delete the specified template map from the server and disables any previously in
|
||||
#### Definition
|
||||
|
||||
<div class="code-title notitle code-request"></div>
|
||||
{% highlight bash %}
|
||||
```bash
|
||||
DELETE /api/v1/map/named/:template_name
|
||||
{% endhighlight %}
|
||||
```
|
||||
|
||||
#### Example
|
||||
|
||||
<div class="code-title code-request">REQUEST</div>
|
||||
{% highlight bash %}
|
||||
```bash
|
||||
curl -X DELETE 'https://documentation.cartodb.com/api/v1/map/named/:template_name?auth_token=AUTH_TOKEN'
|
||||
{% endhighlight %}
|
||||
```
|
||||
|
||||
<div class="code-title">RESPONSE</div>
|
||||
{% highlight javascript %}
|
||||
```javascript
|
||||
{
|
||||
"error": "Some error string here"
|
||||
}
|
||||
{% endhighlight %}
|
||||
```
|
||||
|
||||
On success, a 204 (No Content) response would be issued. Otherwise a 4xx response with with an error will be returned:
|
||||
|
||||
@ -571,9 +571,9 @@ This allows you to get a list of all available templates.
|
||||
#### Definition
|
||||
|
||||
<div class="code-title notitle code-request"></div>
|
||||
{% highlight bash %}
|
||||
```bash
|
||||
GET /api/v1/map/named/
|
||||
{% endhighlight %}
|
||||
```
|
||||
|
||||
#### Params
|
||||
|
||||
@ -582,23 +582,23 @@ GET /api/v1/map/named/
|
||||
#### Example
|
||||
|
||||
<div class="code-title code-request with-result">REQUEST</div>
|
||||
{% highlight bash %}
|
||||
```bash
|
||||
curl -X GET 'https://documentation.cartodb.com/api/v1/map/named?api_key=APIKEY'
|
||||
{% endhighlight %}
|
||||
```
|
||||
|
||||
<div class="code-title with-result">RESPONSE</div>
|
||||
{% highlight javascript %}
|
||||
```javascript
|
||||
{
|
||||
"template_ids": ["@template_name1","@template_name2"]
|
||||
}
|
||||
{% endhighlight %}
|
||||
```
|
||||
|
||||
<div class="code-title">ERROR</div>
|
||||
{% highlight javascript %}
|
||||
```javascript
|
||||
{
|
||||
"error": "Some error string here"
|
||||
}
|
||||
{% endhighlight %}
|
||||
```
|
||||
|
||||
### Getting a Specific Template
|
||||
|
||||
@ -607,9 +607,9 @@ This gets the definition of a template
|
||||
#### Definition
|
||||
|
||||
<div class="code-title notitle code-request"></div>
|
||||
{% highlight bash %}
|
||||
```bash
|
||||
GET /api/v1/map/named/:template_name
|
||||
{% endhighlight %}
|
||||
```
|
||||
|
||||
#### Params
|
||||
|
||||
@ -618,20 +618,20 @@ GET /api/v1/map/named/:template_name
|
||||
#### Example
|
||||
|
||||
<div class="code-title code-request with-result">REQUEST</div>
|
||||
{% highlight bash %}
|
||||
```bash
|
||||
curl -X GET 'https://documentation.cartodb.com/api/v1/map/named/:template_name?auth_token=AUTH_TOKEN'
|
||||
{% endhighlight %}
|
||||
```
|
||||
|
||||
<div class="code-title with-result">RESPONSE</div>
|
||||
{% highlight javascript %}
|
||||
```javascript
|
||||
{
|
||||
"template": {...} // see template.json above
|
||||
}
|
||||
{% endhighlight %}
|
||||
```
|
||||
|
||||
<div class="code-title">ERROR</div>
|
||||
{% highlight javascript %}
|
||||
```javascript
|
||||
{
|
||||
"error": "Some error string here"
|
||||
}
|
||||
{% endhighlight %}
|
||||
```
|
||||
|
Loading…
Reference in New Issue
Block a user