From cc0ebf70a75783f65969d70e66e5cd53e72f149f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Carlos=20Matall=C3=ADn?= Date: Wed, 28 Oct 2015 16:55:11 +0100 Subject: [PATCH] docs: static maps --- docs/static_maps_api.md | 111 ++++++++++++++++++++++------------------ 1 file changed, 61 insertions(+), 50 deletions(-) diff --git a/docs/static_maps_api.md b/docs/static_maps_api.md index 8f9c22ad..ff97673b 100644 --- a/docs/static_maps_api.md +++ b/docs/static_maps_api.md @@ -17,38 +17,43 @@ GET /api/v1/map/static/center/:token/:z/:lat/:lng/:width/:height.:format #### Params -* **:token**: the layergroupid token from the map instantiation -* **:z**: the zoom level of the map -* **:lat**: the latitude for the center of the map -* **:lng**: the longitude for the center of the 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. +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 + +:format | the format for the image, supported types: `png`, `jpg` +--- | --- +|_ jpg | will have a default quality of 85. ### Bounding Box #### Definition -
```bash GET /api/v1/map/static/bbox/:token/:bbox/:width/:height.:format` ``` #### Params -* **:token**: the layergroupid token from the map instantiation -* **: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` - * **jpg** will have a default quality of 85. +Param | Description +--- | --- +:token | the layergroupid token from the map instantiation -Note: you can see this endpoint as: +: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` + +:format | the bounding box in WGS 84 (EPSG:4326), comma separated values for: +--- | --- +|_ jpg | will have a default quality of 85. ```bash GET /api/v1/map/static/bbox/:token/:west,:south,:east,:north/:width/:height.:format` @@ -58,22 +63,26 @@ 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 ``` #### 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. +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 + +: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 +#### 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. @@ -95,22 +104,24 @@ The Static Maps API allows for multiple layers of incorporation into the `MapCon By manipulating the `"urlTemplate"` custom basemaps can be used in generating static images. Supported map types for the Static Maps API are: - 'http://{s}.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}.png', - 'http://{s}.basemaps.cartocdn.com/dark_nolabels/{z}/{x}/{y}.png', - 'http://{s}.basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png', - 'http://{s}.basemaps.cartocdn.com/light_nolabels/{z}/{x}/{y}.png', +``` +'http://{s}.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}.png', +'http://{s}.basemaps.cartocdn.com/dark_nolabels/{z}/{x}/{y}.png', +'http://{s}.basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png', +'http://{s}.basemaps.cartocdn.com/light_nolabels/{z}/{x}/{y}.png', +``` **Mapnik** ```javascript - { - "type": "mapnik", - "options": { - "sql": "select null::geometry the_geom_webmercator", - "cartocss": "#layer {\n\tpolygon-fill: #FF3300;\n\tpolygon-opacity: 0;\n\tline-color: #333;\n\tline-width: 0;\n\tline-opacity: 0;\n}", - "cartocss_version": "2.2.0" - } - }, +{ + "type": "mapnik", + "options": { + "sql": "select null::geometry the_geom_webmercator", + "cartocss": "#layer {\n\tpolygon-fill: #FF3300;\n\tpolygon-opacity: 0;\n\tline-color: #333;\n\tline-width: 0;\n\tline-opacity: 0;\n}", + "cartocss_version": "2.2.0" + } +}, ``` **CartoDB** @@ -118,14 +129,14 @@ By manipulating the `"urlTemplate"` custom basemaps can be used in generating st As described in the [Mapconfig documentation](https://github.com/CartoDB/Windshaft/blob/0.44.1/doc/MapConfig-1.3.0.md), a "cartodb" type layer is now just an alias to a "mapnik" type layer as above, intended for backwards compatibility. ```javascript - { - "type": "cartodb", - "options": { - "sql": "select * from park", - "cartocss": "/** simple visualization */\n\n#park{\n polygon-fill: #229A00;\n polygon-opacity: 0.7;\n line-color: #FFF;\n line-width: 0;\n line-opacity: 1;\n}", - "cartocss_version": "2.1.1" - } - }, +{ + "type": "cartodb", + "options": { + "sql": "select * from park", + "cartocss": "/** simple visualization */\n\n#park{\n polygon-fill: #229A00;\n polygon-opacity: 0.7;\n line-color: #FFF;\n line-width: 0;\n line-opacity: 1;\n}", + "cartocss_version": "2.1.1" + } +} ``` Additionally, static images from Torque maps and other map layers can be used together to generate highly customizable and versatile static maps. @@ -142,17 +153,17 @@ It is important to note that generated images are cached from the live data refe * JPEG quality by default is 85% * Timeout limits for generating static maps are the same across the CartoDB Editor and Platform. It is important to ensure timely processing of queries. - ## Examples After instantiating a map from a CartoDB account: -
REQUEST
+#### Call + ```bash GET /api/v1/map/static/center/4b615ff367e498e770e7d05e99181873:1420231989550.8699/14/40.71502926732618/-73.96039009094238/600/400.png ``` -### Response +#### Response

static-api