Map Image API Developer's Guide

The Mapview Resource

The map resource returns a position based on latitude and longitude or geocoding (address based location search), reverse geocoding (showing address information), and POIs (with and without markers).

The map resource supports different zoom levels, map schemes such as normal, terrain, satellite or hybrid, image sizes and formats, scale bars, and Picture-in-Picture map.

In addition to the representation of a particular position it is possible to display one or more points of interest, given by the corresponding geocoordinates. By default the POI markers are shown in given locations but it is also possible to use the POI coordinates without the markers to show a map of the area which contains all the given locations.

Resource URI

/?[c=...]

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. If you use the app ID/app code option, you need to include an `app_id` and `app_code` with every request. For more informatino on authentication, see the Identity & Access Management Developer Guide.
app_code	String	Typically, but not guaranteed to be, 20 bytes Base64 URL-safe encoded string used for the authentication of the client application. If you use the app ID/app code option, you need to include an `app_id` and `app_code` with every request. For more information on authentication, see the Identity & Access Management Developer Guide.
apiKey	String	A 43-byte Base64 URL-safe encoded string used for the authentication of the client application. As a logged in user, you can generate it at https://developer.here.com/projects. API Keys never expire but you can invalidate your API Keys at any time. You cannot have more than two API Keys for one app at the same time.
bbox	Geo Coordinate list	Any number of coordinates can be given in any order. It will create a bounding box for those coordinates. Note: If `poi` or `poix` are given, then this parameter is ignored. Note: If this parameter is provided, it ignores `tx`, `tx.xy`, `ctr`, `ectr`. Note: If this parameter is provided then the geo search parameters are ignored, such as `co`.
c	Geo Coordinate	Position geo coordinate. The position marker dot is shown in this location if `nodot` parameter is not present. Used also as map center point if `ctr`,`ectr`, POIs (parameter `poi`) or custom text labels (parameter `tx0`,`tx1`,...) are not requested. Ignored if parameter `e` is specified. Ignored if a geo search is also requested.
ci	String	City name for address based search. UTF-8 encoded and URL-encoded.
co	String	Country name for address based search. UTF-8 encoded and URL-encoded.
ctr	Geo Coordinate	Map center point geo coordinate. If the position is on the border of the map, the dot might be cropped. Note: For Basic Map: If center point is not given in the request, the position parameter will be used as the center point, if no POIs (parameter `poi`) or custom text labels (parameter `tx0`,`tx1`,...) are requested. If the center point parameter is provided it is preferred over a given position parameter. In this situation, it is possible that the requested position (parameter `c`) is out of the map image. This parameter is ignored if parameter `ectr` is provided or POIs (parameter poi) or custom text labels (parameter `tx0,tx1,...`) are requested. Ignored if a geo search is also requested. Note: For Route: Using this overrides the automatically calculated route center point. Using this also enables free zoom level definition i.e. also zooming in (not only zooming out) is possible from automatically calculated zoom level.
e	Encoded Geo Coordinate	Encoded equivalent of position geo coordinate parameter `c`. Parameter `c` is ignored if this parameter is specified.
ectr	Encoded Geo Coordinate	Encoded equivalent of map center point geo coordinate parameter `ctr`. Parameter `ctr` is ignored if this parameter is present.
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.
i	Boolean	Flag for showing address or position information box inside the map image (if address is available or position is allowed to be shown). Note: If geo search parameters such as `co` are provided, then the information shown is related to those parameter's values, if valid.
lat	Latitude	Latitude. Used together with longitude parameter `lon`. Note: For Basic Map: The latitude parameter takes no effect if position with parameter `c` or `e` is requested.
lon	Longitude	Longitude. Used together with latitude parameter lat. Note: For Basic Map: The longitude parameter takes no effect if position with parameter `c` is requested.
maxhits	Integer	Maximum number of search results to return. Applies only when some kind of search is performed which can return multiple results. Set to 1 to show directly the first matching result without any results listing.
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.
ml2	String	Second language to be used, only for dual labelling, therefore a `ml` language must also be present. 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.
n	String	House number on the street for address based search.
nocmp	Flag	Flag for hiding the compass on the map. Note: The compass is automatically hidden if the image is smaller than 240. The compass size is calculated determining the final map image width and height. The size is 40 if image is 240, otherwise is 0.1 times the size of the image minus 100.
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.
nodot	Flag	Flag for hiding position marker dot on the map. This has an effect only if position is requested.
nomrk	Integer	If present without a value, is used as a flag for hiding POI markers on the map. Otherwise the value provided will be used as a margin in pixels around the POIs to the image border. This has an effect only if POIs are requested with parameter `poi`. This flag can be used together with `poi` to define multiple geocoordinates that should be included on the shown map but without any markers.
pip	Integer	Shows small Picture-in-Picture map from the same location as the actual requested map on bottom right corner of the map image, using the given value as zoom level for the PiP-map. Positive value is used as absolute zoom level for the PiP-map and a negative value is interpreted as the number of levels to zoom out from main map's zoom level. If the parameter is provided, but no value or no valid value for the parameter is specified, the main map's zoom level zoomed out by 5 levels is used for the PiP-map. The PiP-map size is related to the requested map size (1/3 of the map's width and height). However, the PiP-map maximum size is 150x150px and the minimum size is 50x50px. Note: When the PiP zoom level is below 3 and fractional, then the value is rounded down. Note: When the PiP zoom level (either auto calculated or given) is equal or greater than the map zoom then the green area will not be shown. Note: The PiP-map is not shown if POIs (parameter poi) without `nomrk` flag are requested . Note: When the parameter `ra` is used, the PiP-map is not rotated if the PiP-map zoom level is below 3.
poi	Geo Coordinate List	List of geo coordinates for Points of Interest. Points are shown on map with markers if flag `nomrk` is not used. The poi will always be cropped if it does not fit in the image. Markers can be customized as a group by setting common defaults for fill color (parameter `poifc`), text color (parameter `poitxc`) and text size (parameter `poitxs`). If customization per single POI marker is needed, the extended POI parameters `poixN` (where N means index 0..n) must be used and all POIs must be defined separately as single extended POIs. Note: For Basic map: When this parameter is used, parameters `ctr, pip` and `txN` (where N means index 0..n) will be ignored. Also parameter i is ignored if this parameter is used without nomrk flag. And this parameter itself is ignored if HTML container is requested (parameter hc) or extended POIs (parameter `poixN` where N means index 0..n) are requested. Note: For Route: POI markers are always shown, but only if they are near enough the route area i.e. POI markers do not affect the automatic zoom level calculation or shown bounding box and can therefore go out of the image. Note: This parameter can not be mixed with parameter `poix`.
poifc	Color	Default fill color for POI markers. This can used to define common default fill color for all POI markers. If no default fill color is available, system default light blue (0xBF0066AA) fill color will be used.
poilbl	Integer	POI marker labeling type. 0 Numerical i.e. 1,2,3,... etc. (default if not provided) 1 Alphabetical i.e. A,B,C,... etc.
poithm	Integer	POI marker theme. 0 Bubble 1 Pin 2 HERE style pin If no theme is available, system default theme 2 (HERE style pin) will be used.
poitxc	Color	Default text color for POI markers. This can used to define common default text color for all POI markers. If no default text color is available, system default white text color will be used.
poitxs	Integer	Default text font size for POI markers, valid range is between 8-30. This can used to define common default text font size for all POI markers. If no default text font size is available, system default text font size `10` will be used.
poix0,poix1,...	Fields	Single extended POI marker characteristics as fields. Fields that can be provided are (in following order): Geo coordinate (mandatory) Latitude and longitude in Geo Coordinate parameter type format. If no value is provided default will be used. Fill color (optional) POI marker fill color in Color parameter type format. If not provided, requested default POI marker fill color (defined via parameter `poifc`) is used. If default not requested, system default POI marker fill color is used. Text color (optional) POI marker text color in Color parameter type format. If not provided, requested default POI marker text color (defined via parameter `poitxc`) is used. If default not requested, system default POI marker text color is used. Text font size (optional) POI marker text font size as integer. Valid range is between 8 and 30. If not provided, requested default POI marker text size (defined via parameter `poitxs`) is used. If default not requested, system default POI marker text font size is used. Custom text (optional) Custom text for POI marker. 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 '\'. If not provided, extended POI marker will get automatic alphabetical or numerical text depending on the requested POI labeling type i.e. parameter `poilbl`. For multiple extended POIs consecutive numbering is necessary in indexes and a gap in sequential numbering leads to ignoring of all the subsequent index parameters. Points are shown on map with markers only if flag nomrk is not used. The overlapping markers are not merged into a single marker, which causes the markers to be drawn on top of each other in given order. Note: For Basic Map: When extended POI parameters are used, parameters ctr,ectr, pip, txN (where N means index 0..n) and poi will be ignored. Also parameter I is ignored if extended POI parameters are used without nomrk flag. And extended POI parameters themselves are ignored if HTML container is requested (parameter `hc`). Note: For Route: POI markers are always shown, but only if they are near enough the route area i.e. POI markers do not affect the automatic zoom level calculation or shown bounding box and can therefore go out of the image. Note: This parameter can not be mixed with parameter poi.
ppi	Integer	Resolution to be used. Only allows below mentioned four 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	Geopolitical 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.
ra	Floating point number	The rotation angle of the map in degrees between 0-360. If given angle is 0, the image is not rotated at all and the compass is not displayed. If angle is greater than 360 or less than 0, the value is normalized (e.g. 380 to 20, -10 to 350). Note: If this parameter is not requested or the value is empty or invalid, an automatic northward orientation (determined by the first two coordinate pairs of the given route points with parameter `r0`) is performed for the map. Note: This parameter is disabled for zoom level less than 3, it will ignore the value . Note: After rotation, it may happen that pois, circles, custom texts or other artifacts on the image may get outside the picture.
rad,rad0,rad1,...	Distance	Radius of an area. Note: Basic Map: Radius of the surrounding area to be shown on map around the map center point. Indexing in parameter name is not supported i.e. plain `rad` must be used. This parameter will be ignored if the zoom level parameter `z` is provided or POIs (with parameter `poi`) or text labels with parameter `txN` (where N means index 0..n) are requested. Note: Region and Heat Map: Radius of a circular area. Radii have to be distinguished by indexes in parameter name when showing multiple circular areas/regions. The index number is used for linking the radius to similarly indexed area/region having only one geo coordinate pair. When presenting only a single circular area/region, the index 0 of the parameter is not required i.e. plain rad can be used. Parameter will be ignored if the corresponding area/region parameter aN (where N means index 0..n) value consists of more than one geo coordinate pair (i.e. it is incorrectly defined). Please be aware that this is not applied when only one area/region exists, since they can have multiple geo coordinate values.
s	String	Street name for address based search. The string must be first UTF-8 encoded and then URL-encoded.
sb	String	Scale bars to show at bottom right corner of the map. The scale bar won't be drawn if it does not properly fit in the image. Value defines whether to show scale bar in kilometers/meters and/or in miles/feet. `k`: Shows scale bar in kilometers/meters. `m`: Shows scale bar in miles/feet. `km` or `mk`: Shows two scale bars, one in kilometers/meters and one in miles/feet. Note: The scale bar won't be drawn if it does not properly fit in the image.
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.
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 `apiKey` 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.
u	Distance	Radius of uncertain area around the requested position. Draws color filled circle having given value as radius around the position marker dot. Note: For Basic Map: For it to be shown, it is required that the position is also requested.
vt	Integer	Map view type. 0 Normal map view. 1 Normal map view without public transport information. 2 Traffic map view without public transport information.
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. Dafault zoom level is 10. 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.
zi	String	Zip/postal code for address based search.