Merge pull request #304 from CartoDB/docs-revamp

Documentation for named maps static images + view option in templates

docs/Map-API.md

@@ -398,6 +398,19 @@ POST /api/v1/map/named
         }
       }
     ]
+  },
+  "view": {
+    "zoom": 4,
+    "center": {
+      "lng": 0,
+      "lat": 0
+    },
+    "bounds": {
+      "west": -45,
+      "south": -45,
+      "east": 45,
+      "north": 45
+    }
   }
 }
 ```
@@ -410,6 +423,16 @@ POST /api/v1/map/named
   - **valid_tokens** when `"method"` is set to `"token"`, the values listed here allow you to instantiate the named map.
 - **placeholders**: Variables not listed here are not substituted. Variables not provided at instantiation time trigger an error. A default is required for optional variables. Type specification is used for quoting, to avoid injections see template format section below.
 - **layergroup**: the layer list definition. This is the MapConfig explained in anonymous maps. See [MapConfig documentation](https://github.com/CartoDB/Windshaft/blob/0.44.1/doc/MapConfig-1.3.0.md) for more info.
+- **view** (optional): extra keys to specify the compelling area for the map. It can be used to have a static preview of a named map without having to instantiate it. It is possible to specify it with `center` + `zoom` or with a bounding box `bbox`. Center+zoom takes precedence over bounding box.
+  - **zoom** The zoom level to use
+  - **center**
+    - **lng** The longitude to use for the center
+    - **lat** The latitude to use for the center
+  - **bounds**
+    - **west**: The western point for the bounding box
+    - **south**: The southern point for the bounding box
+    - **east**: The eastern point for the bounding box
+    - **north**: The northern point for the bounding box
 
 #### Template Format
 
@@ -747,6 +770,8 @@ The Static Maps API can be initiated using both named and anonymous maps using t
 
 Begin by instantiating either a named or anonymous map using the `layergroupid token` as demonstrated in the Maps API documentation above. The `layergroupid` token calls to the map and allows for parameters in the definition to generate static images.
 
+#### Zoom + center
+
 ##### Definition
 
 <div class="code-title notitle code-request"></div>
@@ -793,6 +818,25 @@ Note: you can see this endpoint as:
 GET /api/v1/map/static/bbox/:token/:west,:south,:east,:north/:width/:height.:format`
 ```
 
+#### Named map
+
+##### Definition
+
+<div class="code-title notitle code-request"></div>
+```bash
+GET /api/v1/map/static/named/:name/:width/:height.:format
+```
+
+##### Params
+
+* **: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`
+  * **jpg** will have a default quality of 85.
+
+A named maps static image will get its constraints from the [view in the template](#Arguments), if `view` is not present it will estimate the extent based on the involved tables otherwise it fallback to `"zoom": 1`, `"lng": 0` and `"lat": 0`.
+
 ####Layers
 
 The Static Maps API allows for multiple layers of incorporation into the `MapConfig` to allow for maximum versatility in creating a static map. The examples below were used to generate the static image example in the next section, and appear in the specific order designated.

docs/MultiLayer-API.md

@@ -1,4 +1,4 @@
-The Windshaft-CartoDB MultiLayer API extends the [Windshaft MultiLayer API](https://github.com/Vizzuality/Windshaft/wiki/Multilayer-API) in a few ways.
+The Windshaft-CartoDB MultiLayer API extends the [Windshaft MultiLayer API](https://github.com/CartoDB/Windshaft/blob/master/doc/Multilayer-API.md) in a few ways.
 
 ## Last modification timestamp embedded in the token
 

docs/Routes.md

@@ -38,6 +38,9 @@ This document list all routes available in Windshaft-cartodb Maps API server.
 1. `GET (?:/api/v1/map/named|/user/:user/api/v1/map/named|/tiles/template) {:user(f)} (1)`
 <br/>Notes: List named maps (w/ API KEY) [1]
 
+1. `GET (?:/api/v1/map|/user/:user/api/v1/map|/tiles/layergroup)/static/named/:template_id/:width/:height.:format {:user(f),:template_id(f),:width(f),:height(f),:format(f)} (1)`
+<br/>Notes: Static map for named maps
+
 1. `GET /health {} (1)`
 <br/>Notes: Healt check
 
@@ -73,10 +76,10 @@ Something like the following patch should do the trick
 
 ```javascript
 diff --git a/lib/cartodb/cartodb_windshaft.js b/lib/cartodb/cartodb_windshaft.js
-index 477a4c2..f69eebb 100644
+index b9429a2..e6cc5f9 100644
 --- a/lib/cartodb/cartodb_windshaft.js
 +++ b/lib/cartodb/cartodb_windshaft.js
-@@ -242,6 +242,20 @@ var CartodbWindshaft = function(serverOptions) {
+@@ -212,6 +212,20 @@ var CartodbWindshaft = function(serverOptions) {
          }
      });