"How to" for web integrators

Integration with Leaflet

The easiest way to integrate the skobbler maps into your own website is by using our skobbler plugin. Here are 4 easy steps to use it:

  1. The skobbler plugin is built on top of Leaflet, the open-source JavaScript library for mobile-friendly interactive maps, so the library must be firstly included into your HTML markup:
    <link rel="stylesheet" href="http://cdn.leafletjs.com/leaflet-0.7.2/leaflet.css" />
    <script src="http://cdn.leafletjs.com/leaflet-0.7.2/leaflet.js"></script>
  2. Our map-tile styles and the skobbler specific map-controls layout, are accessible in Leaflet via our plugin. Simply include skobbler.js plugin just below the leaflet library inclusion, like this:
    <link rel="stylesheet" href="http://cdn.leafletjs.com/leaflet-0.7.2/leaflet.css" />
    <script src="http://cdn.leafletjs.com/leaflet-0.7.2/leaflet.js"></script>
    
    <script src="PATH_TO_SKOBBLER.js"></script>
  3. You can select our map position into your website, by simply choosing a unique ID for any HTML DIV-tag you want. A height for your DIV element is mandatory, since a 0 height DIV will not be able to display the map:
    <link rel="stylesheet" href="http://cdn.leafletjs.com/leaflet-0.7.2/leaflet.css" />
    <script src="http://cdn.leafletjs.com/leaflet-0.7.2/leaflet.js"></script>
    
    <script src="PATH_TO_SKOBBLER.js"></script>
    
    <style>
        #map {
            height: 500px;
        }
    </style>
    
    <div id="map"></div>
  4. You can initialize the map by specifying only the ID you chose earlier, and your API key (the credentials needed to use our API, yours being found here):
    <link rel="stylesheet" href="http://cdn.leafletjs.com/leaflet-0.7.2/leaflet.css" />
    <script src="http://cdn.leafletjs.com/leaflet-0.7.2/leaflet.js"></script>
    
    <script src="PATH_TO_SKOBBLER.js"></script>
    
    <style>
        #map {
            height: 500px;
        }
    </style>
    
    <div id="map"></div>
    
    <script>
        var map = L.skobbler.map('map', {
            apiKey: 'YOUR_API_KEY'
        });
    </script>
    In this case, the map will have the default set of options we thought to be appropriate for most of our users. However, a specific set of options can be defined like this:
    <script>
        var map = L.skobbler.map('map', {
            apiKey: 'YOUR_API_KEY',
    
            mapStyle: 'day',
            bicycleLanes: true,
            onewayArrows: true,
            pois: 'all',
            primaryLanguage: 'en',
            fallbackLanguage: 'en',
            mapLabels: 'localNaming',
            retinaDisplay: 'auto',
    
            zoomControl: true,
            zoomControlPosition: 'top-left',
    
            center: [52.52112, 13.40554],
            zoom: 12
        });
    </script>
After integrating our plugin, any one of the Leaflet specific actions, layers, markers etc can be added and played with on the newly created map object:
var marker = L.marker([52.52112, 13.40554]).addTo(map);
marker.bindPopup("Hello world!<br>I am a popup.", { offset: new L.Point(-1, -41) }).openPopup();
For the verbose and well documented list of possible customization, see the Leaflet site and documentation. Next, we provide you with all our possible map options, nicely explained:

Option Type Default Description
apiKey string null Find your web api key on the Api key page
mapStyle string 'day' Tile styling can be chosen from the following options: day, night, lite, bike or outdoor
bicycleLanes boolean true Show or hide the bicycle lanes
onewayArrows boolean true Show or hide the one way arrows for the one way streets
pois string 'all' You can choose to populate the map with Point of Interest (POIs). Pick from: all, important or none
primaryLanguage string 'en' Chose one of the supported languages by using the following country codes: en, de, fr, it, es, ru
fallbackLanguage string 'en' Choose the backup language, for those places which have no naming available in the primary language. The codes are: en, de, fr, it, es, ru
mapLabels string 'localNaming' You can pick one of the following map labeling methods: localNaming, transliterationOnly, noTransliteration, nativeLocalized, transliterationNative
retinaDisplay string 'auto' By specifying the retina setting, you can set the map behavior when viewed from a retina-capable device: auto, on, off
zoomControl boolean true Show or hide the zoom controls
zoomControlPosition string 'top-left' The location of the zoom controls, if visible: top-left, top-right, bottom-left or bottom-right
center string null Specify the initial map center, as desired
zoom number null Specify the initial zoom level from a range of 0 to 18

RealReach

RealReach provides features like the maximum possible walking / driving / biking coverage, given a chosen time frame, by nicely drawing a blueish area above our maps.

This is the RealReach URL:

http://YOUR_API_KEY.tor.skobbler.net/tor/RSngx/RealReach/json/13_1/ro/YOUR_API_KEY
                        
And this is an example of a request:

http://YOUR_API_KEY.tor.skobbler.net/tor/RSngx/RealReach/json/13_1/ro/YOUR_API_KEY?start=44.4325,26.1039&transport=pedestrian&range=180&units=sec&toll=1&highways=1&nonReachable=0&response_type=gps
                        
Here is another request example:

http://YOUR_API_KEY.tor.skobbler.net/tor/RSngx/RealReach/json/13_1/ro/YOUR_API_KEY?startMercator=18024748,11004862&transport=pedestrian&range=180&units=sec&toll=1&highways=1&nonReachable=0&response_type=mercator
                        
Here are the list of options that you can use, along with explanations:
Option Type Default Description
YOUR_API_KEY string null Find your web api key on the Api key page
start string Center of RealReach in GPS coordinates: Latitude, Longitude
startMercator string Center of RealReach in mercator coordinates: X,Y (Where X corresponds to Longitude and Y to Latitude). Has priority over start, when both are present
transport string You can pick one of the transport options: pedestrian, bike, car
range int The range for which we calculate RealReach
units string You can choose between sec and meter. 'Sec' is for time and 'Meter' is for distance
nonReachable boolean Specifies whether to calculate or not the interior contours (non reachable areas) inside the RealReach
toll boolean You can specify whether to avoid or not the use of toll roads in route calculation
highways boolean Specifies whether to avoid or not the use of highways in route calculation
response_type string You can choose how you want to get the results, in 'gps' or 'mercator' points
You can see RealReach in action just below:
Because of the 'cross domain policy' restriction AJAX has, for the moment, you need to set up a 'proxy' on your server in order to fetch the information. Here is an example written in PHP:

<?php

$defaults = array(
    CURLOPT_HEADER => 0,
    CURLOPT_URL => 'http://YOUR_API_KEY.tor.skobbler.net/tor/RSngx/RealReach/json/13_1/ro/YOUR_API_KEY?start=44.4325,26.1039&transport=pedestrian&range=180&units=sec&toll=1&highways=1&nonReachable=0&response_type=gps',
    CURLOPT_FRESH_CONNECT => 1,
    CURLOPT_RETURNTRANSFER => 1,
    CURLOPT_FORBID_REUSE => 1,
    CURLOPT_TIMEOUT => 60
);

$curlSession = curl_init();
curl_setopt_array($curlSession, $defaults);
$result = curl_exec($curlSession);
curl_close($curlSession);

?>
                        
The variable '$result' now contains all the information you need and you can parse the points using javascript to create the area layer.

Tile server & Static map

Overview

The server provides raster map images according to the provided configuration parameters.

  Main services
  • map tiles service according to the XYZ schema
  • static map (single image)
  Main features
  • more map styles to choose from
  • high-level map customization
  • label internationalization (i18n)
  • retina support

Tile server

Form:

http://SUBDOMAIN-YOUR_API_KEY.skobblermaps.com/TileService/OP_MODE/VERSION/SETTING_FLAGS/STYLE_ID/Z/X/Y.EXT@2x
                        
Examples:

http://tiles2-YOUR_API_KEY.skobblermaps.com/TileService/tiles/2.0/010011101/0/10/550/335.png
                        


http://tiles3-YOUR_API_KEY.skobblermaps.com/TileService/tiles/2.0/110011101/10/6/34/20.png@2x
                        

Static map

Form:

http://SUBDOMAIN-YOUR_API_KEY.skobblermaps.com/TileService/OP_MODE/VERSION/SETTING_FLAGS/STYLE_ID/LAT,LON,ZOOM/WIDTHxHEIGHT.EXT@2X
                        
Examples:

http://tiles1-YOUR_API_KEY.skobblermaps.com/TileService/static/2.0/00001210100/5/52.50326,13.39387,12/450x320.png
                        

Parameters

Name Description Mandatory
SUBDOMAIN Subdomain aliases
Useful to circumvent browser limitations on parallel resource loading from the same domain; improves download performance on client side
Possible values: tiles1, tiles2, tiles3, tiles4
YES
OP_MODE Operation mode:
tiles - for standard XYZ tiles
static - for static map (single image)
YES
YOUR_API_KEY The client's API key, alphanumeric string
To obtain an API key subscribe at http://developer.skobbler.com/
YES
VERSION Possible values:
2.0
YES
SETTING_FLAGS Map setting flags as alphanumeric string, each character representing a setting.
Please check the possible settings and flag values below.
YES
STYLE_ID Style-ID (numeric)
At the moment the following default styles are supported:
0 - day
2 - night
5 - outdoor
7 - light
10 - bicycle
For client-specific custom styles please contact us.
YES
EXT Image format (extension)
Currently supported formats:
  png<MAXIMUM_COLORS>
   MAXIMUM_COLORS = [3-256] (default: server dependant), e.g. png64
  jpg<IMAGE_QUALITY>, jpeg<IMAGE_QUALITY>
   IMAGE_QUALITY = [1,100] (default: 80), e.g. jpg60
YES
@2x Retina image modifier, for non-retina it should be omitted
If used, the returned image will have double of the initial size. The content of the image will be identical (or very similar) to the non-retina version.
NO

  Tile server specific parameters

X X tile number according to the standard XYZ schema YES
Y Y tile number according to the standard XYZ schema YES
Z Zoom level, supported values [0,18] YES

  Static map specific parameters

LAT Latitude coordinate of the map center (ex. 52.33952) YES
LON Longitude coordinate of the map center (ex. 8.98018) YES
ZOOM Zoom level [0-18] YES
WIDTH Image width in pixels, supported values [16,1024] YES
HEIGHT Image width in pixels, supported values [16,1024] YES

Setting flags

The settings flags allow high-level map customization. Each option is represented by one flag. The choice for using flags instead of individual parameters was made to shorten the URL and facilitate caching (ex. CloudFront)
The SETTINGS_FLAGS is an alphanumeric string, each character represents a flag. At the moment only numeric values are used, but if more than ten values will be needed in the future the alpha chars will also be used. There is no rule whether the flags start with value 0 or 1, this varies to better match their meaning.

Structure:

BICYCLE_LANES | ONEWAY ARROWS | HEIGHTMAP | POIS | PRIMARY_LANG | FALLBACK_LANG | FIRST_LABEL | SECOND_LABEL | SHOW_AND/OR_LABELS | TRANSLIT_BACKUP | RESERVED_I18N | CLUSTERING

Name Description Mandatory Default
BICYCLE_LANES Render bicycle lanes:
0 - no
1 - yes
YES 0
ONEWAY ARROWS Render oneway arrows
0 - no
1 - yes
NO 0
HEIGHTMAP Render heightmap (relief shading)
0 - no
NO 0
POIS Render POIs
0 - no
1 - only important POIs (STYLE_ID-dependant)
2 - all
NO 0
PRIMARY_LANG Primary language choice for the labels
1 - EN
2 - DE
3 - FR
4 - IT
5 - ES
6 - RU
NO 1
FALLBACK_LANG Fallback language (this language will be used if there is no label corresponding to the primary language)
1 - EN
2 - DE
3 - FR
4 - IT
5 - ES
6 - RU
NO 1
FIRST_LABEL What names to show for the first part of the label
1 - local
  e.g. In Germany , you'll see e.g. 'München', in Russia 'Москва', in Japan '東京'
2 - transliterated - to Latin or Cyrillic, depending on the alphabet of the primary language
  e.g. 'Moskva' in Russia or 'Dong Jing' in Japan
3 - international - names will be displayed based on the primary/fallback language
  e.g. If the language is set to English, names will read e.g. 'Moscow', 'Munich', 'Tokyo'.
NO 3
SECOND_LABEL What name to show for the second part of the label
0 - none
1 - local
  e.g. In Germany , you'll see e.g. 'München', in Russia 'Москва', in Japan '東京')
2 - transliterated - to Latin or Cyrillic, depending on the alphabet of the primary language
  e.g. 'Moskva' in Russia or 'Dong Jing' in Japan
3 - international - names will be displayed based on the primary/fallback language
  e.g. If the language is set to English, names will read e.g. 'Moscow', 'Munich', 'Tokyo'.
NO 1
SHOW_AND/OR_LABELS To show one of two names for each label
1 - OR, show only one label
  if the first exists that one, else the second
2 - AND, show both labels, the second in parentheses
  e.g. 'München (Munich)' Note: the second label will be shown only if it is not identical to the first
NO 1
TRANSLIT_BACKUP Transliteration backup: use transliteration as backup if international name is missing
0 - no
1 - yes
NO 1
RESERVED_I18N Reserved flag for future Internationalization options NO 0
CLUSTERING Flag for clustering elements on the map
0 - no
1 - yes
NO 0

Example: 010212132101

Status codes

Requests for images (tile or static) return HTTP status codes according to the HTTP standards. The response's content is either the image or empty (on error).

HTTP Status Code HTTP Status Message Details
200 OK Success, the image is returned
304 Not modified Indicates that the image has not been modified since the last request
403 Forbidden Indicates that the used API key is invalid
404 File not found Indicates that there is no image matching the provided URL parts or parameters
5xx Server specific errors