cartodb4/Windshaft-cartodb
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

consistent placeholder examples with brackets

Browse Source
This commit is contained in:
csobier
2016-03-22 09:19:50 -04:00
parent 85e5a89298
commit 8547cb836f
4 changed files with 63 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/anonymous_maps.md
+13 -13
View File
@@ -36,7 +36,7 @@ The response includes:
Attributes | Description
--- | ---
layergroupid | The ID for that map, used to compose the URL for the tiles. The final URL is: `https://{account}.cartodb.com/api/v1/map/:layergroupid/{z}/{x}/{y}.png`
layergroupid | The ID for that map, used to compose the URL for the tiles. The final URL is: `https://{username}.cartodb.com/api/v1/map/{layergroupid}/{z}/{x}/{y}.png`
updated_at | The ISO date of the last time the data involved in the query was updated.
metadata | Includes information about the layers.
cdn_url | URLs to fetch the data using the best CDN for your zone.
@@ -46,7 +46,7 @@ cdn_url | URLs to fetch the data using the best CDN for your zone.
#### Call
```bash
curl 'https://documentation.cartodb.com/api/v1/map' -H 'Content-Type: application/json' -d @mapconfig.json
curl 'https://{documentation}.cartodb.com/api/v1/map' -H 'Content-Type: application/json' -d @mapconfig.json
```
#### Response
@@ -79,7 +79,7 @@ When you have a layergroup, there are several resources for retrieving layergoup
These tiles will get just the Mapnik layers. To get individual layers, see the following section.
```bash
https://documentation.cartodb.com/api/v1/map/c01a54877c62831bb51720263f91fb33:0/{z}/{x}/{y}.png
https://{documentation}.cartodb.com/api/v1/map/{c01a54877c62831bb51720263f91fb33:0}/{z}/{x}/{y}.png
```
#### Individual layers
@@ -89,21 +89,21 @@ The MapConfig specification holds the layers definition in a 0-based index. Laye
Individual layers can be accessed using that 0-based index. For UTF grid tiles:
```bash
https://documentation.cartodb.com/api/v1/map/c01a54877c62831bb51720263f91fb33:0/:layer/{z}/{x}/{y}.grid.json
https://{documentation}.cartodb.com/api/v1/map/{c01a54877c62831bb51720263f91fb33:0}/{layer}/{z}/{x}/{y}.grid.json
```
In this case, `:layer` as 0 returns the UTF grid tiles/attributes for layer 0, the only layer in the example MapConfig.
In this case, `{layer}` as 0 returns the UTF grid tiles/attributes for layer 0, the only layer in the example MapConfig.
If the MapConfig had a Torque layer at index 1 it could be possible to request it with:
```bash
https://documentation.cartodb.com/api/v1/map/c01a54877c62831bb51720263f91fb33:0/1/{z}/{x}/{y}.torque.json
https://{documentation}.cartodb.com/api/v1/map/{c01a54877c62831bb51720263f91fb33:0}/1/{z}/{x}/{y}.torque.json
```
#### Attributes defined in `attributes` section
```bash
https://documentation.cartodb.com/api/v1/map/c01a54877c62831bb51720263f91fb33:0/:layer/attributes/:feature_id
https://{documentation}.cartodb.com/api/v1/map/{c01a54877c62831bb51720263f91fb33:0}/{layer}/attributes/{feature_id}
```
Which returns JSON with the attributes defined, like:
@@ -115,19 +115,19 @@ Which returns JSON with the attributes defined, like:
#### Blending and layer selection
```bash
https://documentation.cartodb.com/api/v1/map/c01a54877c62831bb51720263f91fb33:0/:layer_filter/{z}/{x}/{y}.png
https://{documentation}.cartodb.com/api/v1/map/{c01a54877c62831bb51720263f91fb33:0}/{layer_filter}/{z}/{x}/{y}.png
```
Note: currently format is limited to `png`.
`:layer_filter` can be used to select some layers to be rendered together. `:layer_filter` supports two formats:
`{layer_filter]` can be used to select some layers to be rendered together. `{layer_filter}` supports two formats:
- `all` alias
Using `all` as `:layer_filter` will blend all layers in the layergroup
Using `all` as `{layer_filter}` will blend all layers in the layergroup
```bash
https://documentation.cartodb.com/api/v1/map/c01a54877c62831bb51720263f91fb33:0/all/{z}/{x}/{y}.png
https://{documentation}.cartodb.com/api/v1/map/{c01a54877c62831bb51720263f91fb33:0}/all/{z}/{x}/{y}.png
```
- Filter by layer index
@@ -135,7 +135,7 @@ https://documentation.cartodb.com/api/v1/map/c01a54877c62831bb51720263f91fb33:0/
A list of comma separated layer indexes can be used to just render a subset of layers. For example `0,3,4` will filter and blend layers with indexes 0, 3, and 4.
```bash
https://documentation.cartodb.com/api/v1/map/c01a54877c62831bb51720263f91fb33:0/0,3,4/{z}/{x}/{y}.png
https://{documentation}.cartodb.com/api/v1/map/{c01a54877c62831bb51720263f91fb33:0}/0,3,4/{z}/{x}/{y}.png
```
Some notes about filtering:
@@ -172,7 +172,7 @@ callback | JSON callback name.
#### Call
```bash
curl "https://documentation.cartodb.com/api/v1/map?callback=callback&config=%7B%22version%22%3A%221.0.1%22%2C%22layers%22%3A%5B%7B%22type%22%3A%22cartodb%22%2C%22options%22%3A%7B%22sql%22%3A%22select+%2A+from+european_countries_e%22%2C%22cartocss%22%3A%22%23european_countries_e%7B+polygon-fill%3A+%23FF6600%3B+%7D%22%2C%22cartocss_version%22%3A%222.3.0%22%2C%22interactivity%22%3A%5B%22cartodb_id%22%5D%7D%7D%5D%7D"
curl "https://{documentation}.cartodb.com/api/v1/map?callback=callback&config={%7B%22version%22%3A%221.0.1%22%2C%22layers%22%3A%5B%7B%22type%22%3A%22cartodb%22%2C%22options%22%3A%7B%22sql%22%3A%22select+%2A+from+european_countries_e%22%2C%22cartocss%22%3A%22%23european_countries_e%7B+polygon-fill%3A+%23FF6600%3B+%7D%22%2C%22cartocss_version%22%3A%222.3.0%22%2C%22interactivity%22%3A%5B%22cartodb_id%22%5D%7D%7D%5D%7D}"
```
#### Response
docs/named_maps.md
+26 -34
View File
@@ -122,7 +122,7 @@ view (optional) | extra keys to specify the view area for the map. It can be use
Placeholders are variables that can be placed in your template.json file. Placeholders need to be defined with a `type` and a default value for MapConfigs. See details about defining a MapConfig `type` for [Layergoup configurations](http://docs.cartodb.com/cartodb-platform/maps-api/mapconfig/#layergroup-configurations).
Valid placeholder names start with a letter and can only contain letters, numbers, or underscores. They have to be written between the `<%=` and `%>` strings in order to be replaced.
Valid placeholder names start with a letter and can only contain letters, numbers, or underscores. They have to be written between the `<%=` and `%>` strings in order to be replaced inside the Named Maps API.
#### Example
@@ -155,7 +155,7 @@ This is the call for creating the Named Map. It is sending the template.json fil
curl -X POST \
-H 'Content-Type: application/json' \
-d @template.json \
'https://documentation.cartodb.com/api/v1/map/named?api_key=APIKEY'
'https://{username}.cartodb.com/api/v1/map/named?api_key={api_key}'
```
#### Response
@@ -164,23 +164,15 @@ The response back from the API provides the name of your MapConfig as a template
```javascript
{
"template_id":"name",
"template_id":"name"
}
```
**Tip:** The colon : in the command signifies where a placeholder variable should be added for an argument, it is not a literal part of the code. For example, a real response might appear as:
```javascript
{
"namedmap_tutorial",
}
```
Note "namedmap_tutorial" is the variable that was used in place of the "template_id". See the [Named Map Tutorial](http://docs.cartodb.com/tutorials/named_maps/), from The Map Academy, for more information about this specific example.
#### Placeholder Errors
As developers use many different methods to input placeholder variables, you may find placeholder examples with other symbols such as, <template_id>, {template_id}, $template_id, or @template_id; indicating that a placeholder variable should be added. If an error is raised, ensure that your placeholder variable appears without any added symbols.
As developers use many different methods to input placeholder variables, you may find external placeholder examples with other symbols such as, <template_id>, :template_id, $template_id, or @template_id; indicating that a placeholder variable should be added. For best practices and consistency, CartoDB uses curly brackets to represent placeholders in our examples. (Note that JSON **Response** examples show “{variable_name}”: “{value}", these are specific to how JSON files are formatted.
If an error is raised during a request, ensure that your placeholder variables appear without any added symbols.
## Instantiate
@@ -190,7 +182,7 @@ Instantiating a Named Map allows you to fetch the map tiles. You can use the Map
#### Definition
```html
POST /api/v1/map/named/:template_name
POST /api/v1/map/named/{template_name}
```
#### Param
@@ -213,7 +205,7 @@ The fields you pass as `params.json` depend on the variables allowed by the Name
#### Example
You can initialize a template map by passing all of the required parameters in a POST to `/api/v1/map/named/:template_name`.
You can initialize a template map by passing all of the required parameters in a POST to `/api/v1/map/named/{template_name}`.
Valid auth token will be needed, if required by the template.
@@ -224,7 +216,7 @@ Valid auth token will be needed, if required by the template.
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'
'https://{documentation}.cartodb.com/api/v1/map/named/{template_name}?auth_token={auth_token}'
```
#### Response
@@ -251,7 +243,7 @@ You can then use the `layergroupid` for fetching tiles and grids as you would no
#### Definition
```bash
PUT /api/v1/map/named/:template_name
PUT /api/v1/map/named/{template_name}
```
#### Params
@@ -276,7 +268,7 @@ Updating a Named Map removes all the Named Map instances, so they need to be ini
curl -X PUT \
-H 'Content-Type: application/json' \
-d @template.json \
'https://documentation.cartodb.com/api/v1/map/named/:template_name?api_key=APIKEY'
'https://{documentation}.cartodb.com/api/v1/map/named/{template_name}?api_key={api_key}'
```
#### Response
@@ -304,7 +296,7 @@ Deletes the specified template map from the server, and disables any previously
#### Definition
```bash
DELETE /api/v1/map/named/:template_name
DELETE /api/v1/map/named/{template_name}
```
#### Params
@@ -318,7 +310,7 @@ api_key | is required
#### Call
```bash
curl -X DELETE 'https://documentation.cartodb.com/api/v1/map/named/:template_name?api_key=APIKEY'
curl -X DELETE 'https://{documentation}.cartodb.com/api/v1/map/named/{template_name}?api_key={api_key}'
```
#### Response
@@ -352,7 +344,7 @@ api_key | is required
#### Call
```bash
curl -X GET 'https://documentation.cartodb.com/api/v1/map/named?api_key=APIKEY'
curl -X GET 'https://{documentation}.cartodb.com/api/v1/map/named?api_key={api_key}'
```
#### Response
@@ -378,7 +370,7 @@ This gets the definition of a requested template.
#### Definition
```bash
GET /api/v1/map/named/:template_name
GET /api/v1/map/named/{template_name}
```
#### Params
@@ -392,7 +384,7 @@ api_key | is required
#### Call
```bash
curl -X GET 'https://documentation.cartodb.com/api/v1/map/named/:template_name?api_key=APIKEY'
curl -X GET 'https://{documentation}.cartodb.com/api/v1/map/named/{template_name}?api_key={api_key}'
```
#### Response
@@ -418,7 +410,7 @@ If using a [JSONP](https://en.wikipedia.org/wiki/JSONP) (for old browsers) reque
#### Definition
```bash
GET /api/v1/map/named/:template_name/jsonp
GET /api/v1/map/named/{template_name}/jsonp
```
#### Params
@@ -433,7 +425,7 @@ callback | JSON callback name
#### Call
```bash
curl 'https://documentation.cartodb.com/api/v1/map/named/:template_name/jsonp?auth_token=AUTH_TOKEN&callback=callback&config=template_params_json'
curl 'https://{documentation}.cartodb.com/api/v1/map/named/{template_name}/jsonp?auth_token={auth_token}&callback=callback&config=template_params_json'
```
#### Response
@@ -470,7 +462,7 @@ You can use a Named Map that you created (which is defined by its `name`), to cr
```javascript
{
user_name: '{your_user_name}', // Required
user_name: '{username}', // Required
type: 'namedmap', // Required
named_map: {
name: '{name_of_map}', // Required, the 'name' of the Named Map that you have created
@@ -521,20 +513,20 @@ Authenticated users, with an auth token, can use XYZ-based URLs to fetch tiles d
To call a template_id in a URL:
`/:template_id/:layer/:z/:x/:y.(:format)`
`/{template_id}/{layer}/{z}/{x}/{y}.{format}`
For example, a complete URL might appear as:
"https://{your user name}.cartodb.com/api/v1/map/named/{template_id}/{layer}/{z}/{x}/{y}.png"
"https://{username}.cartodb.com/api/v1/map/named/{template_id}/{layer}/{z}/{x}/{y}.png"
The placeholders indicate the following:
- [`template_id`](http://docs.cartodb.com/cartodb-platform/maps-api/named-maps/#response) is the response of your Named Map.
- layers can be a number (referring to the # layer of your map), all layers of your map, or a list of layers.
- To show just the basemap layer, enter the number value `0` in the layer placeholder "https://{your user name}.cartodb.com/api/v1/map/named/{template_id}/0/{z}/{x}/{y}.png"
- To show the first layer, enter the number value `1` in the layer placeholder "https://{your user name}.cartodb.com/api/v1/map/named/{template_id}/1/{z}/{x}/{y}.png"
- To show all layers, enter the value `all` for the layer placeholder "https://{your user name}.cartodb.com/api/v1/map/named/{template_id}/all/{z}/{x}/{y}.png"
- To show a [list of layers](http://docs.cartodb.com/cartodb-platform/maps-api/anonymous-maps/#blending-and-layer-selection), enter the comma separated layer value as 0,1,2 in the layer placeholder. For example, to show the basemap and the first layer, "https://{your user name}.cartodb.com/api/v1/map/named/{template_id}/0,1/{z}/{x}/{y}.png"
- To show just the basemap layer, enter the number value `0` in the layer placeholder "https://{username}.cartodb.com/api/v1/map/named/{template_id}/0/{z}/{x}/{y}.png"
- To show the first layer, enter the number value `1` in the layer placeholder "https://{username}.cartodb.com/api/v1/map/named/{template_id}/1/{z}/{x}/{y}.png"
- To show all layers, enter the value `all` for the layer placeholder "https://{username}.cartodb.com/api/v1/map/named/{template_id}/all/{z}/{x}/{y}.png"
- To show a [list of layers](http://docs.cartodb.com/cartodb-platform/maps-api/anonymous-maps/#blending-and-layer-selection), enter the comma separated layer value as 0,1,2 in the layer placeholder. For example, to show the basemap and the first layer, "https://{username}.cartodb.com/api/v1/map/named/{template_id}/0,1/{z}/{x}/{y}.png"
### Get Mapnik Retina Tiles
@@ -543,4 +535,4 @@ Mapnik Retina tiles are not directly supported for Named Maps, so you cannot use
Instantiate the map by using your `layergroupid` in the token placeholder:
`:token/:z/:x/:y@:scale_factor?x.:format`
`{token}/{z}/{x}/{y}@{scale_factor}?{x}.{format}`
docs/quickstart.md
+5 -5
View File
@@ -22,10 +22,10 @@ $.ajax({
type: 'POST',
dataType: 'json',
contentType: 'application/json',
url: 'https://documentation.cartodb.com/api/v1/map',
url: 'https://{documentation}.cartodb.com/api/v1/map',
data: JSON.stringify(mapconfig),
success: function(data) {
var templateUrl = 'https://documentation.cartodb.com/api/v1/map/' + data.layergroupid + '/{z}/{x}/{y}.png'
var templateUrl = 'https://{documentation}.cartodb.com/api/v1/map/' + data.layergroupid + '/{z}/{x}/{y}.png'
console.log(templateUrl);
}
})
@@ -61,7 +61,7 @@ The MapConfig needs to be sent to CartoDB's Map API using an authenticated call.
#### Call
```bash
curl 'https://{account}.cartodb.com/api/v1/map/named?api_key=APIKEY' -H 'Content-Type: application/json' -d @mapconfig.json
curl 'https://{username}.cartodb.com/api/v1/map/named?api_key={api_key}' -H 'Content-Type: application/json' -d @mapconfig.json
```
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.
@@ -69,7 +69,7 @@ To get the `URL` to fetch the tiles you need to instantiate the map, where `temp
#### Call
```bash
curl -X POST 'https://{account}.cartodb.com/api/v1/map/named/:template_id' -H 'Content-Type: application/json'
curl -X POST 'https://{username}.cartodb.com/api/v1/map/named/{template_id}' -H 'Content-Type: application/json'
```
The response will return JSON with properties for the `layergroupid`, the timestamp (`last_updated`) of the last data modification and some key/value pairs with `metadata` for the `layers`.
@@ -96,5 +96,5 @@ Note: all `layers` in `metadata` will always have a `type` string and a `meta` d
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:
```bash
https://documentation.cartodb.com/api/v1/map/c01a54877c62831bb51720263f91fb33:0/{z}/{x}/{y}.png
https://{documentation}.cartodb.com/api/v1/map/{c01a54877c62831bb51720263f91fb33:0}/{z}/{x}/{y}.png
```
docs/static_maps_api.md
+19 -20
View File
@@ -11,18 +11,18 @@ Begin by instantiating either a Named or Anonymous Map using the `layergroupid t
#### Definition
```bash
GET /api/v1/map/static/center/:token/:z/:lat/:lng/:width/:height.:format
GET /api/v1/map/static/center/{token}/{z}/{lat}/{lng}/{width}/{height}.{format}
```
#### Params
Param | Description
--- | ---
:token | the layergroupid token from the map instantiation
:z | the zoom level of the map
:lat | the latitude for the center of the map
token | the layergroupid token from the map instantiation
z | the zoom level of the map
lat | the latitude for the center of the map
:format | the format for the image, supported types: `png`, `jpg`
format | the format for the image, supported types: `png`, `jpg`
--- | ---
&#124;_ jpg | will have a default quality of 85.
@@ -31,33 +31,33 @@ Param | Description
#### Definition
```bash
GET /api/v1/map/static/bbox/:token/:bbox/:width/:height.:format`
GET /api/v1/map/static/bbox/{token}/{bbox}/{width}/{height}.{format}`
```
#### Params
Param | Description
--- | ---
:token | the layergroupid token from the map instantiation
token | the layergroupid token from the map instantiation
:bbox | the bounding box in WGS 84 (EPSG:4326), comma separated values for:
bbox | the bounding box in WGS 84 (EPSG:4326), comma separated values for:
--- | ---
| LowerCorner longitude, in decimal degrees (aka most western)
| LowerCorner latitude, in decimal degrees (aka most southern)
| UpperCorner longitude, in decimal degrees (aka most eastern)
| UpperCorner latitude, in decimal degrees (aka most northern)
:width | the width in pixels for the output image
:height | the height in pixels for the output image
:format | the format for the image, supported types: `png`, `jpg`
width | the width in pixels for the output image
height | the height in pixels for the output image
format | the format for the image, supported types: `png`, `jpg`
:format | the bounding box in WGS 84 (EPSG:4326), comma separated values for:
format | the bounding box in WGS 84 (EPSG:4326), comma separated values for:
--- | ---
&#124;_ jpg | will have a default quality of 85.
Note: you can see this endpoint as
```bash
GET /api/v1/map/static/bbox/:token/:west,:south,:east,:north/:width/:height.:format`
GET /api/v1/map/static/bbox/{token}/{west,south,east,north}/{width}/{height}.{format}`
```
### Named Map
@@ -65,19 +65,18 @@ GET /api/v1/map/static/bbox/:token/:west,:south,:east,:north/:width/:height.:for
#### Definition
```bash
GET /api/v1/map/static/named/:name/:width/:height.:format
GET /api/v1/map/static/named/{name}/{width}/{height}.{format}
```
#### Params
Param | Description
--- | ---
:name | the name of the Named Map
:width | the width in pixels for the output image
:height | the height in pixels for the output image
:height | the height in pixels for the output image
name | the name of the Named Map
width | the width in pixels for the output image
height | the height in pixels for the output image
:format | the format for the image, supported types: `png`, `jpg`
format | the format for the image, supported types: `png`, `jpg`
--- | ---
&#124;_ jpg | will have a default quality of 85.
@@ -161,7 +160,7 @@ After instantiating a map from a CartoDB account:
#### Call
```bash
GET /api/v1/map/static/center/4b615ff367e498e770e7d05e99181873:1420231989550.8699/14/40.71502926732618/-73.96039009094238/600/400.png
GET /api/v1/map/static/center/{4b615ff367e498e770e7d05e99181873:1420231989550.8699/14/40.71502926732618/-73.96039009094238/600/400.png}
```
#### Response