The Region Resource
The Region Resource creates a map image with outlined and filled regions (circles and polygons).
It also supports different map schemes, image sizes, image formats (auto detect possibility by using user agent recognizer) as well as showing scale bar, zooming out from automatically calculated zoom level and customizing the fill colors and outlines for regions.
Regions allow outlining or filling a specified region/area with defined color. It is possible to define circle and polygon areas.
The zoom level for the map image is determined automatically based on the area coordinates and display size (width and height parameters). A given zoom level is only considered if it is smaller than the calculated one to provide a wider view of the map.
Resource URI
/region?[a=...]... Resource Parameters
| Parameter | Type | Description |
|---|---|---|
| a,a0,a1,... | Geo Coordinate List | Area/region coordinates. The parameter values represent coordinate pairs of latitude and longitude. The number of coordinates per parameter determines the geometrical shape of the presented area/region:
a can be used. Note: Extra parameters not corresponding to any a will be ignored . For example providing a l1 parameter without the corresponding a1 parameter will be ignored. |
| 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_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 |
| 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. |
| f | Integer | Image format. It is possible to request the map image in following formats:
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. |
| fc,fc0,fc1,... | Color | Fill color. Fill colors have to be distinguished by indexes when showing multiple areas/regions i.e. fc0, fc1 etc. The index number is used for linking the fill color to similarly indexed area/region. When presenting only a single area/region, the index 0 of the parameter is not required i.e. plain fc can be used.
Note: For Region, if no parameter a is given, this parameter will be ignored. |
| 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. |
| lc,lc0,lc1,... | Color | Line color. When presenting only a single route or area/region, the index 0 of the parameter is not required i.e. plain lc can be used. If no line colors are defined, default blue line colors are used. Note: For Region: Outline color of area/region. It is used only if fill color fc for corresponding index is not given i.e. outline and fill color cannot be combined. If no outline color is defined for some area/region, default fill color will be used for it, if fill color for corresponding area/region index is not given. The parameter is ignored if no a parameter is given. Note: For Route: Route line color.Consecutive numbering is necessary in indexes and a gap in sequential numbering leads to ignoring of all the subsequent index parameters and those will get the color of the last available indexed line color parameter before the gap. Note: For Turning Point: This is the arrow line color. Use parameter lc without index for Turning Point since it does not support the indexing i.e. multiple line colors. |
| lw,lw0,lw1,... | Integer | Line width. When presenting only a single route or area/region, the index 0 of the parameter is not required i.e. plain lw can be used. If no line widths are defined, default value 4 for line widths is used. Note: Valid values are from 1 to 20. Note: For Region: Outline width of area/region. Outline width is used only if outline color lc for corresponding index is given, and fill color fc for corresponding index is not given. Note: For Route: Route line width. Consecutive numbering is necessary in indexes and a gap in sequential numbering leads to ignoring of all the subsequent index parameters and those will get the width of the last available indexed line width parameter before the gap. The final line width consists of this line width and the additional border (shadow) line width (one pixel on both sides of the line) but only if the border line color is not set fully transparent for the route line with similarly indexed parameter sc. Note: For Turning Point: Arrow line width.Use parameter lw without index for Turning Point since it does not support the indexing i.e. multiple line widths. The final line width consists of this line width and the additional border (shadow) line width (one pixel on both sides of the line) but only if the border line color is not set fully transparent for the arrow line with parameter sc. Note: For Routing: Since only one route is supported only one value will be used. Therefore lw or lw0 might be used, but only one of them. The rest of the values provided will be ignored. |
| ml | String | Map label language.
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. |
| ppi | Integer | [Public] Resolution to be used. Only allows below mentioned four values:
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:
|
| 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. |
| 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. |
| 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.
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. |
| strict | Flag | Flag for validating the request in strict mode. If the flag is provided request will be validated in strict mode. If the server is already running in strict mode, then it will supercede this parameter. |
| 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:
|
| 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:
|
| 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.
|
| 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.
|
| 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.
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
|
| txs | Integer | Default text font size for custom texts defined with
|
| txsc | Color | Default text border color for custom texts defined with
|
| w | Integer | Result image width in pixels, maximum 2048.
Note: For Roadsign and Companylogo: minimum is 24, maximum is 256. |
| z | Float | Zoom level for the map.
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. |
