From 8547cb836f4391c5de5169cf102958773363db09 Mon Sep 17 00:00:00 2001 From: csobier Date: Tue, 22 Mar 2016 09:19:50 -0400 Subject: [PATCH] consistent placeholder examples with brackets --- docs/anonymous_maps.md | 26 +++++++++--------- docs/named_maps.md | 60 ++++++++++++++++++----------------------- docs/quickstart.md | 10 +++---- docs/static_maps_api.md | 39 +++++++++++++-------------- 4 files changed, 63 insertions(+), 72 deletions(-) diff --git a/docs/anonymous_maps.md b/docs/anonymous_maps.md index 0769d0fc..50fa354e 100644 --- a/docs/anonymous_maps.md +++ b/docs/anonymous_maps.md @@ -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 diff --git a/docs/named_maps.md b/docs/named_maps.md index 68deab7e..53c0d688 100644 --- a/docs/named_maps.md +++ b/docs/named_maps.md @@ -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, 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, 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}` diff --git a/docs/quickstart.md b/docs/quickstart.md index 057a74e4..55d88fda 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -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 ``` diff --git a/docs/static_maps_api.md b/docs/static_maps_api.md index 9fc7ae4f..a2260753 100644 --- a/docs/static_maps_api.md +++ b/docs/static_maps_api.md @@ -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` --- | --- |_ 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: --- | --- |_ 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` --- | --- |_ 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