Protocol

Four commands are available and are documented in the next sections.

Every command uses the HTTP status code to notify errors.

info.json

HTTP command:

GET {PRINT_URL}/info.json?url={PRINT_URL}%2Finfo.json&var=printConfig

Returns a JSON structure as such:

var printConfig = {
    "scales":[
        {"name":"25000"},
        {"name":"50000"},
        {"name":"100000"}
    ],
    "dpis":[
        {"name":"190"},
        {"name":"254"}
    ],
    "outputFormats":[
        {"name":"pdf"},
        {"name":"png"}
    ],
    "layouts":[
        {
            "name":"A4 portrait",
            "map":{
                "width":440,
                "height":483
            }
        }
    ],
    "printURL":"http:\/\/localhost:5000\/print\/print.pdf",
    "createURL":"http:\/\/localhost:5000\/print\/create.json"
}

This can be loaded through an HTML script tag like that:

<script type="text/javascript"
      src="http://localhost:5000/print/info.json?var=printConfig"></script>

or through an AJAX request, in this case the var query parameter will be omitted.

The “url” query parameter is here to help the print servlet to know what URL is used by the browser to access the servlet. This parameter is here because the servlet can be behind a proxy, hiding the real URL.

create.json

HTTP command:

POST {PRINT_URL}/create.json?url={PRINT_URL}%2Fcreate.json

The spec defined in the “print.pdf” command must be included in the POST body.

Returns a JSON structure like that:

{
    getURL: 'http:\/\/localhost:5000\/print\/56723.pdf'
}

The URL returned can be used to retrieve the PDF file. See the next section.

{ID}.pdf

This command’s URL is returned by the “create.json” command.

HTTP command:

GET {PRINT_URL}/{ID}.pdf

Returns the PDF. Can be called only during a limited time since the server side temporary file is deleted afterwards.

Multiple maps on a single page

To print more than one map on a single page you need to:
  • specify several map blocks in a page of the yaml file, each with a distinct name property value
  • use a particular syntax in the spec to bind different rendering properties to each map block

This is possible specifying a _maps_ object in spec root object with a distinct key - object pair for each map. The key will refer the map block name as defined in yaml file. The object will contain layers and srs for the named map. Another _maps_ object has to be specified inside the page object to describe positioning, scale and so on.

{
    ...
    maps: {
        "main": {
            layers: [
                ...
            ],
            srs: 'EPSG:4326'
        },
        "other": {
            layers: [
                ...
            ],
            srs: 'EPSG:4326'
        }
    },
    ...
    pages: [
        {
            maps: {
                "main": {
                    center: [6, 45.5],
                    scale: 4000000,
                    dpi: 190,
                    geodetic: false,
                    strictEpsg4326: false,
                    ...CUSTOM_PARAMS...
                },
                "other": {
                    center: [7.2, 38.6],
                    scale: 1000000,
                    dpi: 300,
                    geodetic: false,
                    strictEpsg4326: false,
                    ...CUSTOM_PARAMS...
                }
            }

        }
    ],
    ...
}

Other config blocks have been enabled to multiple maps usage. The scalebar block can be bound to a specific map, specifying a name property that matches the map name. Also, in text blocks you can use the ${scale.<mapname>} placeholder to print the scale of the map whose name is <mapname>.

Layers Params

Vector

Type: vector

Render vector layers. The geometries and the styling comes directly from the spec JSON.

  • opacity (Defaults to 1.0)
  • geoJson (Required) the geoJson to render
  • styleProperty (Defaults to ‘_style’) Name of the property within the features to use as style name. The given property may contain a style object directly.
  • styles (Optional) dictonary of styles. One style is defined as in OpenLayers.Feature.Vector.style.
  • name (Defaults to vector) the layer name.

WMS

Type: wms

Support for the WMS protocol with possibilities to go through a WMS-C service (TileCache).

  • opacity (Defaults to 1.0)
  • baseURL (Required) Service URL
  • customParams (Optional) Map, additional URL arguments
  • layers (Required)
  • styles (Optional)
  • format (Required)
  • version (Defaults to 1.1.1)
  • useNativeAngle (Defaults to false) it true transform the map angle to customParams.angle for GeoServer, and customParams.map_angle for MapServer.

WMTS

Type: wmts

Support for the protocol using directly the content of a WMTS tiled layer, support REST or KVP.

Two possible mode, standard or simple, the simple mode imply that all the topLeftCorner are identical.

Standard mode:

  • opacity (Defaults to 1.0)
  • baseURL the ‘ResourceURL’ available in the WMTS capabilities.
  • customParams (Optional) Map, additional URL arguments
  • layer (Required) the layer name
  • version (Defaults to 1.0.0) WMTS protocol version
  • requestEncoding (Defaults to REST) REST or KVP
  • style (Optional) the style name
  • dimensions (Optional) list of dimensions names
  • params (Optional) dictionary of dimensions name (capital) => value
  • matrixSet (Required) the name of the matrix set
  • matrixIds (Required) array of matrix ids e.g.:
[{
    "identifier": "0",
    "matrixSize": [1, 1],
    "resolution": 4000,
    "tileSize": [256, 256],
    "topLeftCorner": [420000, 350000]
}, ...]
  • format (Optional, Required id requestEncoding is KVP)

Simple mode:

  • baseURL base URL without the version.
  • layer (Required)
  • version (Required)
  • requestEncoding (Required) REST
  • tileOrigin (Required)
  • tileSize (Required)
  • extension (Required)
  • resolutions (Required)
  • style (Required)
  • tileFullExtent (Required)
  • zoomOffset (Required)
  • dimensions (Optional)
  • params (Optional)
  • formatSuffix (Required)

Tms

Type: tms

Support the TMS tile layout.

  • opacity (Defaults to 1.0)
  • baseURL (Required) Service URL
  • customParams (Optional) Map, additional URL arguments
  • maxExtent (Required) Array, extent coordinates [420000, 30000, 900000, 350000]
  • tileSize (Required) Array, tile size e.g. [256, 256]
  • format (Required)
  • layer (Required)
  • resolutions (Required) Array of resolutions
  • tileOrigin (Optional) Object, tile origin. Defaults to 0,0

Resources:

Xyz

Type: xyz

Support the tile layout z/x/y.<extension>.

  • opacity (Defaults to 1.0)
  • baseURL (Required) Service URL
  • customParams (Optional) Map, additional URL arguments
  • maxExtent (Required) Array, extent coordinates [420000, 30000, 900000, 350000]
  • tileSize (Required) Array, tile size e.g. [256, 256]
  • resolutions (Required) Array of resolutions (Required) Array of resolutions
  • extension (Required) file extension (Required) file extension
  • tileOrigin (Optional) Array, tile origine e.g. [420000, 350000]
  • tileOriginCorner tl or bl (Defaults to bl)
  • path_format (Optional) url fragment used to construct the tile location. Can support variable replacement of ${x}, ${y}, ${z} and ${extension}. Defaults to zz/x/y.extension format. You can use multiple “letters” to indicate a replacable pattern (aka, ${zzzz} will ensure the z variable is 0 padded to have a length of AT LEAST 4 characters).

Osm

Type: osm

Support the OSM tile layout.

  • opacity (Defaults to 1.0)
  • baseURL (Required) Service URL
  • customParams (Optional) Map, additional URL arguments
  • maxExtent (Required) Array, extent coordinates [420000, 30000, 900000, 350000]
  • tileSize (Required) Array, tile size e.g. [256, 256]
  • resolutions (Required) Array of resolutions
  • extension (Required) file extension

TileCache

Type: tileCache

Support for the protocol using directly the content of a TileCache directory.

  • opacity (Defaults to 1.0)
  • baseURL (Required) Service URL
  • customParams (Optional) Map, additional URL arguments
  • layer (Required)
  • maxExtent (Required) Array, extent coordinates [420000, 30000, 900000, 350000]
  • tileSize (Required) Array, tile size e.g. [256, 256]
  • resolutions (Required) Array of resolutions
  • extension (Required) file extension

Image

Type: image

  • opacity (Defaults to 1.0)
  • name (Required)
  • baseURL (Required) Service URL
  • extent (Required)

MapServer

Type: mapServer

Support mapserver WMS server.

  • opacity (Defaults to 1.0)
  • baseURL (Required) Service URL
  • customParams (Optional) Map, additional URL arguments
  • layers (Required)
  • format (Required)

KaMap

Type: kaMap

Support for the protocol using the KaMap tiling method

  • opacity (Defaults to 1.0)
  • baseURL (Required) Service URL
  • customParams (Optional) Map, additional URL arguments
  • map
  • group
  • maxExtent (Required) Array, extent coordinates [420000, 30000, 900000, 350000]
  • tileSize (Required) Array, tile size e.g. [256, 256]
  • resolutions (Required) Array of resolutions
  • extension (Required) file extension

KaMapCache

Type: kaMapCache

Support for the protocol talking direclty to a web-accessible ka-Map cache generated by the precache2.php script.

  • opacity (Defaults to 1.0)
  • baseURL (Required) Service URL
  • customParams (Optional) Map, additional URL arguments
  • map (Required)
  • group (Required)
  • metaTileWidth (Required)
  • metaTileHeight (Required)
  • units (Required)
  • maxExtent (Required) Array, extent coordinates [420000, 30000, 900000, 350000]
  • tileSize (Required) Array, tile size e.g. [256, 256]
  • resolutions (Required) Array of resolutions
  • extension (Required) file extension

Google

Type: google or tiledGoogle

They used the Google Map Static API, tiledGoogle will create tiles and google only one image.

The google map reader has several custom parameters that can be added to the request they are:

  • opacity (Optional, Defaults to 1.0)
  • baseURL (Required, should be ‘http://maps.google.com/maps/api/staticmap‘)
  • customParams (Optional) Map, additional URL arguments
  • maxExtent (Required, should be [-20037508.34, -20037508.34, 20037508.34, 20037508.34])
  • resolutions (Required, should be [156543.03390625, 78271.516953125, 39135.7584765625, 19567.87923828125, 9783.939619140625, 4891.9698095703125, 2445.9849047851562, 1222.9924523925781, 611.4962261962891, 305.74811309814453, 152.87405654907226, 76.43702827453613, 38.218514137268066, 19.109257068634033, 9.554628534317017, 4.777314267158508, 2.388657133579254, 1.194328566789627, 0.5971642833948135, 0.29858214169740677, 0.14929107084870338, 0.07464553542435169])
  • extension (Required, should be png)
  • client (Optional)
  • format (Optional)
  • maptype (Required) - type of map to display: http://code.google.com/apis/maps/documentation/staticmaps/#MapTypes
  • sensor (Optional) - specifies whether the application requesting the static map is using a sensor to determine the user’s location
  • language (Optional) - language of labels.
  • markers (Optional) - add markers to the map: http://code.google.com/apis/maps/documentation/staticmaps/#Markers
markers: ['color:blue|label:S|46.5195933305192,6.566684726913701']

path: 'color:0x0000ff|weight:5|46.5095933305192,6.506684726913701|46.5195933305192,6.526684726913701|46.5395933305192,6.536684726913701|46.5695933305192,6.576684726913701',

Warranty disclaimer and license

The authors provide these documents “AS-IS”, without warranty of any kind either expressed or implied.

Document under Creative Common License Attribution-Share Alike 2.5 Generic.

Authors: MapFish developers.