Map Image API Developer's Guide

The Statistics Resource

The Statistics resource draws statistics graph objects (bars and circles) to specified locations on the map.

It supports also different map schemes, image sizes (auto detect possibility by using user agent recognizer), image formats (auto detect possibility by using user agent recognizer) as well as customizing the colors for the graph objects.

Statistical Graphs allow displaying statistical data on the map. Currently circle diagrams and bar charts are supported.

The biggest value of the statistical graph(s) takes half of the image height/width at maximum. The minimum size for an object is 10 pixels. If the statistical representation objects overlap each other, none of these objects are drawn.

The zoom level for the map image is determined automatically based on the graph's coordinates, graph values and display size (width and height parameters). A given zoom level is only considered if it is smaller than the calculated one but it may cause the graphs to overlap.

Resource URI

/stat?[ml=...]

Resource Parameters

Parameter Type Description
app_id String

Typically, but not guaranteed to be, 20 bytes Base64 URL-safe encoded string used for the authentication of the client application. See Acquiring Credentials.

app_code String

Typically, but not guaranteed to be, 20 bytes Base64 URL-safe encoded string used for the authentication of the client application. See Acquiring Credentials.

f Integer
Image format. It is possible to request the map image in following formats:
  • 0 PNG
  • 1 JPEG (default)
  • 2 GIF
  • 3 BMP
  • 4 PNG8
  • 5 SVG (only for companylogo)
If this is not given, JPEG is used as default.
Note: For PNG8 images some of the colors may differ compared to full color images so use it with precaution.
Note: For SVG: parameters w and h are ignored.
Note: For Roadsign: Only PNG format is available.
Note: For Companylogo: Only PNG and SVG formats is available.
h Integer

Result image height in pixels, maximum 2048. Height and width parameter can be provided independently, i.e. there is no need to enter both to resize the image.

ml String
Map label language.


Specifies the language to be used to display descriptions of details inside the map image.
If the parameter is not provided, the default language depends on the highest prioritized locale of the
client's Accept-Language HTTP header which is currently supported.
If no map language based on HTTP header can be determined, the server configured default is used.

If the map language is locked on the server config, this parameter (or alternatively the Accept-Language HTTP header) has no effect, i.e. the locked map language is used. The following MARC three-letter language codes are supported currently (the language codes are case insensitive):
  • ara – Arabic
  • baq – Basque
  • cat – Catalan
  • chi – Chinese (simplified)
  • cht – Chinese (traditional)
  • cze – Czech
  • dan – Danish
  • dut – Dutch
  • eng – English
  • fin – Finnish
  • fre – French
  • ger – German
  • gle – Gaelic
  • gre – Greek
  • heb – Hebrew
  • hin – Hindi
  • ind – Indonesian
  • ita – Italian
  • nor – Norwegian
  • per – Persian
  • pol – Polish
  • por – Portuguese
  • rus – Russian
  • sin – Sinhalese
  • spa – Spanish
  • swe – Swedish
  • tha – Thai
  • tur – Turkish
  • ukr – Ukrainian
  • urd – Urdu
  • vie – Vietnamese
  • wel – Welsh
The language code is case insensitive. If the parameter is not provided, the map language is selected based on Accept-Language header locale values as follows:
  • en* English
  • zh* Chinese
  • de* German
  • fr* French
  • it* Italian
  • es* Spanish
  • ru* Russian
  • ar* Arabic
Note: The languages listed in this document might not be up to date as they are dependant on the specific configuration on the server.
nocrop Flag

Flag to avoid having cropped labels on the map. If the parameter is present in the request, the labels that do not fit completely on the image requested will not be on the map, if the parameter is not present, the default behavior will apply, that is, showing the labels even if they are cropped.

nocp Flag
Flag for hiding copyright information on the map.
Note: When this parameter is used, parameter scp will be ignored.
o,o0,o1,.. Fields
Statistical graph object characteristics as fields. Fields that can be provided are (in following order):
  • Geo coordinate (mandatory)

    Latitude and longitude in Geo Coordinate parameter type format.

  • Value (mandatory)

    The represented statistic value as integer or floating point number. The size of the drawn graph object depends on the ratio between this value and other graphs' values.

  • Fill color (optional)

    Graph object fill color in Color parameter type format. If not provided, requested default fill color (defined via parameter ofc) is used. If default not requested, system default fill color is used.

  • Outline color (optional)

    Graph object outline color in Color parameter type format. If not provided, requested default outline color (defined via parameter osc) is used. If default not requested, outline is not drawn.

    Latitude and longitude can be either the center point or the bottom point for the graph, behavior can be selected by using parameter olp. Statistics graphs have to be distinguished by indexes in parameter name when showing multiple graphs on same map i.e. o0, o1 etc. Consecutive numbering is necessary in indexes and a gap in sequential numbering leads to ignoring of all the subsequent index parameters. When presenting only a single graph, the index 0 of the parameter is not required i.e. plain o can be used.

ofc Color

Default fill color for statistical graph objects. This can used to define common default fill color for all graph objects. If no default fill color is available, system default fill color will be used.

olp Integer
Location point for statistical graph objects. Defines which point of the drawn graph objects the given graph objects' geo coordinate locations represent.
  • 0 Center-center (default if not provided)
  • 1 Bottom-center
osc Color

Default border color for statistical graph objects. This can used to define common default border color for all graph objects. If no default border color is available, borders are not drawn for those graph objects missing the border color definition.

ot Integer
Type of representation for statistical graph objects.
  • 0 Circle (default if not provided)
  • 1 Bar
ppi Integer

[Public]

Resolution to be used. Only allows three values:
  • 72 (default)
  • 250 (mobile)
  • 320 (hi-res)
  • 500
. Invalid values are ignored. Only works with
  • t=0 normal.day
  • t=2 terrain.day
  • t=3 hybrid.day
  • t=4 normal.day.transit
  • t=5 normal.day.grey
  • t=13 pedestrian.day
  • t=14 pedestrian.night
Note: When using this parameter the size of the logo will be adjusted to match the resolution.
Note: Please note that mobile schemes can only be used with 250 ppi value, as mixing mobile and non mobile parameters is not allowed.
pview String
Geopolotical View to be used. Use this parameter to render the map with boundaries based on international or local country views. Not specifying the parameter results in a default view of boundaries. If the parameter is specified and the view is supported, boundaries of the selected country view are being shown. The list includes but is not limited to:
  • arg (Argentinian View)
  • ind (Indian View)
  • MAR (Morocco View)
  • PAK (Pakistani View)
q Integer

Image compression quality in percentage between 1-100, default is 85 if not specified. The parameter takes effect only if JPEG image format is used.

scp String
ID of service owner specific copyright. Shows service specific additional copyright information together with map data copyright. The value must be a valid ID/key of a pre-configured service specific copyright i.e. the parameter value itself is not shown on map.
Note: This parameter is ignored if flag parameter nocp is requested. The service specific copyright is not shown if it does not properly fit to the image.
shd Flag

Flag for showing drop shadow of statistical graph objects.

strict Flag

Flag for validating in strict mode the request or not, if the server is already on strict mode it will make no effect.

style String
Map style type. All available styles are defined by Map view server of the Map Image API. The list includes but is not limited to:
  • alps
  • daisy
  • dreamworks
  • flame
  • fleet
  • mini
t Integer
Map scheme type. All available schemes are defined by Map view server of the Map Image API API. Currently this API supports the following set of schemes:
  • 0 (normal.day)

    Normal map view in day light mode.

  • 1 (satellite.day)

    Satellite map view in day light mode.

  • 2 (terrain.day)

    Terrain map view in day light mode.

  • 3 (hybrid.day)

    Satellite map view with streets in day light mode.

  • 4 (normal.day.transit)

    Normal grey map view with public transit in day light mode.

  • 5 (normal.day.grey)

    Normal grey map view in day light mode (used for background maps).

  • 6 (normal.day.mobile)

    Normal map view for small screen devices in day light mode.

  • 7 (normal.night.mobile)

    Normal map view for small screen devices in night mode.

  • 8 (terrain.day.mobile)

    Terrain map view for small screen devices in day light mode.

  • 9 (hybrid.day.mobile)

    Satellite map view with streets for small screen devices in day light mode.

  • 10 (normal.day.transit.mobile)

    Normal grey map view with public transit for small screen devices in day light mode.

  • 11 (normal.day.grey.mobile)
  • 12 (carnav.day.grey) Map view designed for navigation devices.
  • 13 (pedestrian.day) Map view designed for pedestrians walking by day.
  • 14 (pedestrian.night) Map view designed for pedestrians walking by night.

    Normal grey map view for small screen devices in day light mode (used for background maps).

    By default normal map view in day light mode (0) is used for non-mobile clients. For mobile clients the default is normal map view for small screen devices in day light mode (6).

token String
An URL-encoded Base64 string of typically, but not guaranteed to be 24 bytes generated based on the user's app ID and received after the registration process of the application.


The usage of token is deprecated and app_code should be used instead.

tx,tx0,tx1,... Fields
Custom text (to be shown on top of map) and its characteristics as fields. Texts must have geo location based positioning. When using geo location, it may affect the map zoom level if other geo coordinate based information is shown at the same time.


This parameter can not be mixed with tx.xy, only
one is allowed.

Fields that can be provided are (in following order):
  • Text location (mandatory)

    Latitude and longitude in Geo Coordinate parameter type format.

  • Text (mandatory)

    The text to be shown. The text must be first UTF-8 encoded and then URL-encoded. New line can be given as URL-encoded by using "%0D%0A" or "%0A". If the text contains the field separator characters, those must be escaped by using preceding backslash '\'.

  • Text color (optional)

    Text color in Color parameter type format. If not provided, requested default text color (defined via parameter txc) is used. If default not requested, system default text color is used.

  • Text border color (optional)

    Text border color in Color parameter type format. If not provided, requested default text border color (defined via parameter txsc) is used. If default not requested, system default text border color is used.

  • Text font size (optional)

    Text font size as integer. If not provided, requested default text size (defined via parameter txs) is used. If default not requested, system default text size is used.

    Latitude/y-axis value and longitude/x-axis value are the center point of the text. Text parameters have to be distinguished by indexes in parameter name when showing multiple texts on same map i.e. tx0, tx1 etc. Consecutive numbering is necessary in indexes and a gap in sequential numbering leads to ignoring of all the subsequent index parameters. When presenting only a single text, the index 0 of the parameter is not required i.e. plain tx can be used.

    Note: For Basic Map: When this parameter is used with geo coordinate based information, that is, without .xy, parameters ctr and ectr are ignored. This parameter itself is ignored if POIs are requested with parameter poi or poiN (where N means index 0..n) and no nomrk is used.
    Note: Keep in mind that when using ra the coordinates of the text will be rotated unless xy is used, in that case it will not be rotated.
tx.xy,tx.xy0,tx.xy1,... Fields
Custom text (to be shown on top of map) and its characteristics as fields. Texts must have image xy-coordinate (pixel) based positioning (where point 0,0 is top left corner of the image). Negative xy-values are interpreted as relational values to image width and height.


This parameter can not be mixed with tx,tx0,tx1 only one is allowed.

Fields that can be provided are (in following order):
  • Text location (mandatory) Latitude and longitude in pixel based xy-coordinate value. The pixel based value is defined by using prefix 'xy.' and then giving x-axis value as integer (between image width and image width as negative) and y-axis value as integer (between image height and image height as negative) separated with comma ','.
  • Text (mandatory) The text to be shown. The text must be first UTF-8 encoded and then URL-encoded. New line can be given as URL-encoded by using "%0D%0A" or "%0A". If the text contains the field separator characters, those must be escaped by using preceding backslash '\'.
  • Text color (optional) Text color in Color parameter type format. If not provided, requested default text color (defined via parameter txc) is used. If default not requested, system default text color is used.
  • Text border color (optional) Text border color in Color parameter type format. If not provided, requested default text border color (defined via parameter txsc) is used. If default not requested, system default text border color is used.
  • Text font size (optional) Text font size as integer. If not provided, requested default text size (defined via parameter txs) is used. If default not requested, system default text size is used.
Latitude/y-axis value and longitude/x-axis value are the center point of the text. Text parameters have to be distinguished by indexes in parameter name when showing multiple texts on same map i.e. tx.xy0, tx.xy1 etc. Consecutive numbering is necessary in indexes and a gap in sequential numbering leads to ignoring of all the subsequent index parameters. When presenting only a single text, the index 0 of the parameter is not required i.e. plain tx.xy can be used.
Note: For Basic Map: When this parameter is used, parameters ctr and ectr are ignored. This parameter itself is ignored if POIs are requested with parameter poi or poiN (where N means index 0..n).
Note: Keep in mind that when using ra the coordinates of the text will not be rotated.
txc Color
Default text color for custom texts defined with txN (where N means index 0..n).


This can used to define common default text color for all custom texts.
If no default text color is available, system default text color will be used.

txs Integer
Default text font size for custom texts defined with txN (where N means index 0..n).


This can used to define common default text font size for all custom texts.
If no default text font size is available, system default text font size will be used.

txsc Color
Default text border color for custom texts defined with txN (where N means index 0..n).


This can used to define common default text border color for all custom texts. If
no default text border color is available, system default text border color will be used.

w Integer
Result image width in pixels, maximum 2048.


Height and width parameter can be provided independently,
i.e. there is no need to enter both to resize the image.

Note: For Roadsign and Companylogo: minimum is 24, maximum is 256.
z Float
Zoom level for the map.


Available levels are defined by Map View server of the Map Image API API, value between 0-20.

Note: When the request contains parameters having geo coordinate lists or multiple parameters having single geo coordinate pair as value, the zoom level is automatically calculated. In these cases the requested zoom level is applied only if it happens to be smaller than the automatically calculated one i.e. zooming out is desired.
Note: For Route: When the request contains also center point (ctr or ectr), the requested zoom level is applied always.
Note: For levels below 5, the width and height cannot be 1024 or higher.
Note: For Tilt Maps: For zoom levels over 5, the ceiling of h/cos(ta) cannot be 2048 or higher. Zoom level is not automatically calculated.