Parameter 1 (string): format of the map. One of svg, gif, jpeg, png, kml or json.
Parameter 2 (array)
- option 1 (simple map). Two possibilities, depending on the type of map (either dutchlanguagearea, municipalities, corop or provinces, as given in Parameter 3).
- With type dutchlanguagearea, to display one series of Kloeke codes: an array with Kloeke-codes or four-digit postal codes (strings). Note: Kloeke-codes and postal codes cannot be used both within the same series. Kloekecodes example:
<array>
<data>
<value>
<string>E017p</string>
</value>
<value>
<string>E031a</string>
</value>
</data>
</array>
Postal codes example:
<array>
<data>
<value>
<string>1053</string>
</value>
<value>
<string>3503</string>
</value>
</data>
</array>
- With type municipalities, corop or provinces: a struct with area codes as the keys and color codes (for highlighting) as the values. Example:
<struct>
<member>
<name>g_0534</name>
<value>
<string>#FFC513</string>
</value>
</member>
<member>
<name>g_0003</name>
<value>
<string>#FFEEAA</string>
</value>
</member>
</struct>
If you want an empty basemap, use an empty struct as the second parameter.
- option 2 (complex map, more than one series of Kloeke-codes displayed): an array of structs.
Required members of every struct:
- offset (int) index number of the series)
- One of kloekecodes (array) array of strings, Kloeke-codes of the series) or postalcodes (array) array of strings, four-digit postal codes. Series with Kloeke-codes and series with postal codes can be used in the same map (but within one series only one of the two can be used).
Optional members of every struct:
- name (string) name of the series, gets displayed in the legend; if not provided, a default name of "series <offset>" is generated.
- series (int), the index number of the parent collection of the current series of Kloeke-codes. Meant to combine different maps. Each parent collection has a different symbol, the child series within them differ only in color.
- symbol: (string) which symbol should be used to draw the current series. For SVG- or bitmap maps one of square, circle, triangle, bar_horizontal, bar_vertical, line_horizontal, line_vertical, slash_left, slash_right, plus or star; for KML maps either one of the previous symbols, or a valid URL. If left empty, a default symbol is used.
- color: (string) the color with which the symbol of the current series should be drawn. Either the name of a color (one of the 140 HTML colors), or a hexadecimal representation of the form #RRGGBB, or or a hexadecimal representation of the form AABBGGRR. The 'AA' (opacity) part only has an effect with KML maps.
- outlinedcolor: (array) array with two colors (strings), respectively fill and outline, with which the symbol of the current series should be drawn. The second color (outline) has no effect with KML maps. outlinedcolor can be used with all symbols, but really only makes sense with square, circle, triangle, bar_horizontal, bar_vertical, or star. Colors can be either the name of a color (one of the 140 HTML colors), or a hexadecimal representation of the form #RRGGBB, or or a hexadecimal representation of the form AABBGGRR. The 'AA' (opacity) part only has an effect with KML maps.
- size: (string) size of the symbol of the current series. For SVG or bitmap maps the default symbol size is 5000, for KML maps it is 0.6. The sizes are converted into each other internally: if size 0.6 is requested and the requested map format is SVG or a bitmap the symbols get size 5000, and vice versa.
If size is smaller than 100 it is assumed that a size at the scale of KML-maps is meant; if size is larger than 100 it is assumed that a size at the scale of SVG is meant.
- link: (string) provides placemarks with a clickable link. Example: http://www.example.com/script.php?kloeke_code=%s. Any %s placeholders will be automatically replaced with the Kloeke code of the placemark.
- target: (string) provides a target for links. Only has an effect when link exists.
- onclick: (string) JavaScript code for "onclick" event on placemarks. Any %s placeholders will be automatically replaced with the Kloeke code of the placemark.
- onmouseover: (string) JavaScript code for "onmouseover" event on placemarks. Any %s placeholders will be automatically replaced with the Kloeke code of the placemark. Note (SVG maps only): if interactive is TRUE, the onmouseover and onmouseout events are already taken.
- onmouseout: (string) JavaScript code for "onmouseout" event on placemarks. Any %s placeholders will be automatically replaced with the Kloeke code of the placemark. Note (SVG maps only): if interactive is TRUE, the onmouseover and onmouseout events are already taken.
Note: link, target, onclick, onmouseover and onmouseout only have a direct effect on SVG maps. If you want to add these features to bitmap maps, you need both a bitmap picture and a list of HTML <area> elements. See below for the imagemap parameter.
Parameter 3 (optional): a struct with parameters about the map as a whole. Possible members:
- additionaldata: (array) Used to add an additional layer of data to a map. Currently only provinces or corop can be added to a map of type municipalities and daan_blok_1969 to a map of type dutchlanguagearea. The latter is synonymous to setting the background to daan_blok_1969.
- altitudedifference (int) the difference (in meters above the earth surface) in height between different series. Only has an effect on KML maps. Default: 50. Only possible with map type dutchlanguagearea.
- background: (string) Background to be drawn between base map and placemarks. Currently only the value daan_blok_1969 is allowed. Only possible with map type dutchlanguagearea.
- imagemap: (boolean) Whether the return value should be an array containing, after the base_64 encoded map, a string with HTML <area> elements for the placemarks. link, target, onclick, onmouseover and onmouseout attributes, if defined, (see above) will be included. This can be used to add interactivity to bitmap maps.
- interactive: (boolean) Whether symbols on the map should show placename and Kloeke code "onmouseover". This only has a direct effect on SVG maps. If you want to add this feature to bitmap maps, you need both a bitmap picture and a list of HTML <area> elements. See below for the imagemap parameter.
- link: (string) Template for a link to be added to placemark or municipalities. %s placeholders will be replaced by either the Kloeke code or the municipality code. For maps of a bitmap format, the links will be added to the imagemap of the picture, for maps of format SVG or KML they will be embedded in the XML. (link = urlencoded form of http://www.example.com/?code=%s). Note: when using placemarks, this only works if there is just one series. If you have more than one series of placemarks, the link parameter should go into the data object, see the example under data above. Applies to all municipalities of a map of type municipalities unless the parameter linkhighlightedonly is set to true.
- linkhighlightedonly: (boolean) Only for maps of type municipalities. If this parameter is set to true, a link set with the link parameter is only added to higlighted municipalities.
- maptype: (string) standard (default) or frequency. Frequency means that a placemark (Kloeke code) which occurs twice is now drawn twice as big, three times becomes three times as big, etc. Note: this does not work yet for KML maps. Only possible with map type dutchlanguagearea.
- parts: (array) an array of strings containing parts of the map which should be drawn. See the output of kaart.getpossibleparts for the list of possibilities. If this member is not present the complete map is drawn. Only possible with map type dutchlanguagearea.
- pixelwidth or width: (int) width of the map in pixels. The height is automatically 0.9 times the width.
- removeduplicates (boolean) Whether duplicates within the same series of Kloeke codes should be removed or not. Default: false. Only possible with map type dutchlanguagearea.
- showcombinations: (boolean) Only useful for maps of map type dutchlanguagearea. If this parameter is set to true, counts of overlapping placemarks between different series will be shown in the legend.
- title: (string) title of the map.
- type: (string) dutchlanguagearea (default) or municipalities/gemeentes (synonyms) or corop or provincies/provinces (synonyms)
NOTE. If postal codes are used, those are translated internally to Kloeke codes (the Kloeke codes which contain the postal codes). This means that the map does not get more detailed if the input is postal codes!
Return value: base64-encoded map in the requested format, or: array containing base64-encoded map and string with HTML <area> elements for use in <map> element.