Name
HTML::OSM - Generate an interactive OpenStreetMap with Leaflet.js
Version
Version 0.19
Synopsis
use HTML::OSM;
my $map = HTML::OSM->new(
coordinates => [
[37.7749, -122.4194, 'San Francisco'],
[undef, undef, 'Paris'],
],
zoom => 10,
);
my ($head, $body) = $map->onload_render();
-
Caching
Geocode results are cached via CHI (default: in-memory, 1-day TTL). Supply your own
cacheobject to persist across processes. -
Rate-Limiting
Set
min_interval(seconds) to throttle outbound Nominatim calls and comply with the API fair-use policy. -
Tile server
tile_urlreplaces the OpenStreetMap tile layer, so a map can use an internal tile server or run on an air-gapped network. It accepts the same Leaflet placeholders as the default, for examplehttp://tiles.internal/{z}/{x}/{y}.png. The attribution remains the OpenStreetMap credit, which is the usual requirement for OSM-derived tiles. The in-page search box still calls Nominatim when a reader uses it; setsearch => 0to leave it out. -
Maximum zoom
max_zoom(0 to 28) stops readers zooming in further than the tile server has tiles for. Without it, Leaflet allows zooming past the server's coverage and the map shows empty grey tiles. When it is not given, no limit is set. -
Tile attribution
tile_attributionreplaces the credit shown in the corner of the map. Set it when the tiles come from a provider that asks for a different credit. The value is HTML that Leaflet renders as it is, so pass only trusted text. -
Nominatim contact address
emailis added to every Nominatim request the module makes, as the Nominatim usage policy asks of heavy users. It is not put into the rendered page, so the in-page search box sends no address. -
Content-Security-Policy
nonceputsnonce="..."on every<script>thatonload_render()writes, the Leaflet and plugin scripts in the head as well as the map's own, so a page whose policy allows scripts only by nonce draws the map without'unsafe-inline'. It must be base64 or base64url (A-Z a-z 0-9 + / _ - =), so it cannot end the attribute;onload_render()checks it again, because a config file or a clone skipsnew()'s check. Give a fresh one for each response. The<style>blocks carry none: the policy'sstyle-srcneeds'unsafe-inline'anyway for the styles Leaflet sets. -
Search box
By default the rendered page has a search box that sends whatever the reader types to Nominatim, and a button that clears the markers it adds. Set
search => 0to leave both out, so that nothing typed on the page leaves the reader's machine. The "Reset Map" button is always included. -
Fitting the markers
By default the map opens at
zoom(12) around the middle of the markers, which can leave them all out of view.fit => 1opens it on every pin and circle marker instead, zooming in no further thanzoom, and the "Reset Map" button returns there. A centre set withcenter()wins. -
Scale and key
scale => 1adds a scale bar, andlegenda key that lists only what is in view. Both change as the reader zooms; see "Scale and key".
Description
HTML::OSM builds an interactive map from OpenStreetMap tiles and the
Leaflet.js library. Give it points as latitude and longitude, as place
names, or as geocoder result objects. It can also draw GeoJSON shapes,
heatmaps, GPX tracks and choropleth (colour-filled region) layers, and can
group nearby markers into clusters. A named GeoJSON layer gets a checkbox on
the map, so the reader can turn it on and off.
Place names are turned into coordinates by an injected geocoder or, without
one, by the Nominatim service. The answers are cached, and requests can be
spaced out with min_interval.
onload_render() returns two HTML fragments: one for the page's
<head> and one for its <body>. The interface follows
HTML::GoogleMaps::V3, so code written for that module needs few changes.
Scale and Key
my $map = HTML::OSM->new(
scale => 1,
legend_title => 'Country',
legend => [
{ label => 'England', colour => '#e41a1c', group => 'en' },
{ label => 'France', colour => '#377eb8', group => 'fr' },
{ label => '100 people', colour => '#888888', radius => 14 },
],
);
$map->add_marker([51.5074, -0.1278], html => 'London', group => 'en');
$map->add_circle_marker([48.8566, 2.3522], html => 'Paris', group => 'fr',
colour => '#377eb8');
scale => 1 adds Leaflet's scale bar, in kilometres and miles, to the
bottom left corner. It is redrawn whenever the map moves or zooms. The
default is no scale bar.
legend draws a key in a corner of the map: legend_position is
topright (the default), topleft, bottomright or bottomleft.
legend_title is printed above the entries. Each entry is a hashref:
-
labelThe text, required. It is written as text, never as HTML.
-
colourA hex colour,
#rgbor#rrggbb, for the round swatch. The default is#3388ff, Leaflet's own blue. -
radiusThe swatch's radius in pixels, for a key to the sizes of circle markers. Without it the swatch is 12 pixels across. A large radius is drawn at most 50 pixels across.
-
groupThe entry is listed only while a marker given the same
group(throughadd_markeroradd_circle_marker) is inside the map's view. Each time the reader pans or zooms, the key is drawn again, so it shows only the entries for what can be seen. A marker hidden in a cluster still counts. An entry without a group is always listed. -
unless_layerThe name of a GeoJSON layer (
add_geojson'sname). The entry is listed only while that layer is hidden: for an entry the layer's ownkeystands in for while the layer is shown, so the reader is not given the same colours twice. When the reader unticks the layer, its key goes and the entry comes back. A name no layer has leaves the entry always listed.
When no entry is listed, the key says legend_empty, by default
"Nothing in this view". When every entry is left out for a layer that is
shown (unless_layer), the key is not drawn at all.
new() croaks on an entry it cannot use, and on an unknown position.
Values from a config file or a clone skip that check, so onload_render()
checks them again. It leaves out a bad entry and uses topright for a bad
position, with a warning.
Subroutines/Methods
New
Construct a new HTML::OSM object.
my $map = HTML::OSM->new(%params);
my $map = HTML::OSM->new(\%params);
Both method-style (HTML::OSM->new(...)) and function-style
(HTML::OSM::new(...)) calls are supported.
Calling $existing_obj->new(%overrides) performs a shallow clone,
merging %overrides onto the existing object's state without re-validating.
Api Specification
Input
{
cache => { type => object, can => [get, set], optional },
cluster => { type => boolean, optional },
cluster_css_url => { type => string, optional },
cluster_default_css_url => { type => string, optional },
cluster_js_url => { type => string, optional },
config_file => { type => string, optional },
coordinates => { type => arrayref, optional },
css_url => { type => string, optional },
email => { type => string, optional },
fit => { type => boolean, optional },
geocoder => { type => object, can => geocode, optional },
gpx_js_url => { type => string, optional },
heatmap_js_url => { type => string, optional },
height => { type => string, optional },
host => { type => string, optional },
js_url => { type => string, optional },
legend => { type => arrayref, optional },
legend_empty => { type => string, optional },
legend_position => { type => string, enum => [topright, topleft, bottomright, bottomleft], optional },
legend_title => { type => string, optional },
logger => { type => object, optional },
max_zoom => { type => integer, min => 0, max => 28, optional },
min_interval => { type => number, min => 0, optional },
nonce => { type => string, matches => qr/\A[A-Za-z0-9+\/_=-]+\z/, optional },
scale => { type => boolean, optional },
search => { type => boolean, optional },
tile_attribution => { type => string, optional },
tile_url => { type => string, optional },
ua => { type => object, optional },
width => { type => string, optional },
zoom => { type => integer, min => 0, max => 19, optional },
}
Output
{ type => object, isa => 'HTML::OSM' }
Messages
| Message | Meaning / Resolution |
|------------------------------------------------|-----------------------------------------------|
| (validation error from Params::Validate::Strict) | A param has the wrong type or is out of range |
| new(): invalid legend_position: VALUE | Not one of topright, topleft, bottomright, bottomleft |
| new(): legend entry N: ... | An entry of legend is unusable; see L</Scale and key> |
Pseudocode
1. If $class is neither a package name nor a blessed ref, treat as
function-style call: prepend $class back onto @_ and use __PACKAGE__.
2. If $class is a blessed ref (clone call): merge override params onto a
shallow copy and return immediately, bypassing schema validation.
3. Validate all supplied args against the declared schema.
4. Merge config-file settings via Object::Configure.
5. Resolve the cache: caller-supplied object, or in-memory CHI instance.
6. Bless and return with Readonly CDN constants as defaults.
Add_Marker
Add a point marker to the map.
$map->add_marker([51.5074, -0.1278], html => 'London');
$map->add_marker('Paris, France', html => 'Paris');
$map->add_marker($geo_coder_result);
Returns 1 on success, 0 if the point cannot be resolved or is out of range. An empty address, or an arrayref that does not hold exactly two elements, also returns 0.
Api Specification
Input
point : arrayref [lat, lon] | string address | object with latitude()/longitude()
html : string (optional popup label)
icon : string (optional icon URL)
group : string (optional; the key entry this marker belongs to, see L</Scale and key>)
Output
{ type => integer, enum => [0, 1] }
Messages
| Message | Meaning / Resolution |
|-----------------------------------------|---------------------------------------------|
| add_marker(): unknown point type: TYPE | Point is a ref type with no lat/lon methods |
| add_marker(): group must be a string | group is a reference |
| Skipping invalid coordinate: (LAT, LON) | Warning: the point is not numeric or is out of range; 0 is returned |
Examples
# Coordinate array with a popup label
$map->add_marker([51.5074, -0.1278], html => 'London');
# String address geocoded via the injected geocoder or Nominatim
$map->add_marker('Paris, France', html => 'Paris');
# Custom icon URL with a popup
$map->add_marker(
[40.7128, -74.0060],
html => 'New York',
icon => 'https://example.com/pin.png',
);
# Geo::Coder result object that implements latitude()/longitude()
my $result = $geocoder->geocode('Berlin, Germany');
$map->add_marker($result, html => 'Berlin');
# Accumulate several markers, warn on geocode failure
for my $city (@cities) {
$map->add_marker($city->{coords}, html => $city->{name})
or warn "Could not place $city->{name}";
}
Add_Circle_Marker
Add a filled circle whose size in pixels can show a quantity, such as the population of a town.
$map->add_circle_marker([51.5074, -0.1278],
html => 'London',
radius => 12,
colour => '#e45c3a',
);
The point may be anything add_marker() accepts. The radius is in screen
pixels, so a circle stays the same size as the reader zooms in and out.
With cluster => 1, circles join the same cluster group as the pin
markers.
Returns 1 on success, 0 if the point cannot be resolved or is out of range.
Api Specification
Input
point : arrayref [lat, lon] | string address | object with latitude()/longitude()
html : string (optional popup label)
radius : number > 0 and < 1e6 (optional, default 8)
colour : string hex #rrggbb or #rgb, any case (optional, default '#3388ff')
group : string (optional; the key entry this circle belongs to, see L</Scale and key>)
Output
{ type => integer, enum => [0, 1] }
Messages
| Message | Meaning / Resolution |
|-----------------------------------------------------|---------------------------------------------|
| add_circle_marker(): radius must be a positive number | radius is 0, negative, 1e6 or more, or not a plain number |
| add_circle_marker(): invalid colour: VALUE | colour is not a #rgb or #rrggbb hex string |
| add_circle_marker(): unknown point type: TYPE | Point is a ref type with no lat/lon methods |
| add_circle_marker(): group must be a string | group is a reference |
| Skipping invalid coordinate: (LAT, LON) | Warning: the point is not numeric or is out of range; 0 is returned |
Examples
# Bubble whose area shows the population
$map->add_circle_marker([$lat, $lon],
html => "$city ($pop)",
radius => sqrt($pop / $max_pop) * 30,
colour => '#e45c3a',
);
# Mixed map: pins for offices, circles for market size
$map->add_marker([$lat1, $lon1], html => 'HQ');
$map->add_circle_marker([$lat2, $lon2], html => 'Market A', radius => 20);
Add_Geojson
Add a GeoJSON layer to the map.
$map->add_geojson(\%data, style => { color => '#ff0000' }, popup => 'name');
The first argument may be a hashref/arrayref (GeoJSON structure) or a JSON string.
Give it a name and the reader can hide and show it (see "LAYER CONTROL").
Returns 1 on success.
Api Specification
Input
data : hashref | arrayref | string (JSON)
style : hashref Leaflet path-style options (color, weight, fillColor, fillOpacity)
popup : string Feature property name whose value becomes the popup text
name : string Label of the layer's checkbox in the map's layer control
show : boolean Whether a named layer is drawn when the map opens (default 1)
key : hashref A key to the layer's colours, shown while the layer is
(see L</LAYER KEY>):
{ entries => [ { label, colour }, ... ], title?, position?,
shape? }
bands : string Feature property holding a list of colours, each drawn
as a line of its own just inside the outline, side by side
(see L</BANDS>)
Output
{ type => integer, value => 1 }
Messages
| Message | Meaning / Resolution |
|-------------------------------------------|---------------------------------|
| (JSON parse error) | data string is not valid JSON |
| add_geojson: name must be a string | name is a reference or empty |
| add_geojson: show must not be a reference | show is a reference |
| add_geojson: key ... | key is unusable; the message |
| | says which part |
| add_geojson: bands must be a string | bands is a reference or empty |
Layer Control
Give a layer a name and the map gains Leaflet's layer control, a box of
checkboxes in its top right corner, one for each name, so the reader can hide
and show that layer. show => 0 starts it hidden: the reader turns it
on. As with search, the strings false, no and off are false.
Layers given the same name share one checkbox, which is ticked when any of
them has show on. A layer with no name is always drawn, whatever show
says, because nothing could turn it on. The control is written once, after
the last GeoJSON layer, and is left open (not collapsed into an icon), so the
reader can see what can be turned on.
The name is shown as text: Leaflet writes it into the page as HTML, so it is
escaped first, and <b> is shown as written.
Layer Key
$map->add_geojson(\%busy, style => { color => '#d73027' }, name => 'Counties',
key => {
title => 'Population',
entries => [
{ label => '100,000 or more', colour => '#d73027' },
{ label => 'under 100,000', colour => '#1a9850' },
],
});
$map->add_geojson(\%quiet, style => { color => '#1a9850' }, name => 'Counties');
key draws a key to a layer's colours in a corner of the map: a short line
of each colour, as an outline is drawn, beside its label. It is shown while
the layer is: unticking the layer's checkbox hides the key too, and ticking it
shows it again. A layer with no name is always drawn, so its key always
shows.
-
entriesRequired, at least one: hashrefs of
label(text, required) andcolour(#rgbor#rrggbb, required), listed in the order given. -
titleText printed above the entries.
-
positionbottomright(the default),bottomleft,toprightortopleft. The marker key (legend) and the layer control are top right by default. -
shapeline(the default) draws each entry's colour as a short line, for a layer of outlines;boxdraws a filled box, for a layer whose areas are filled.
Layers that share a name share one key: the first key given for that name.
Every text reaches the page as text, never as HTML.
Bands
# Kent's outline is red with blue inside it; Surrey's is all green
$kent->{properties}{colours} = [ '#d73027', '#4575b4' ];
$surrey->{properties}{colours} = [ '#1a9850' ];
$map->add_geojson({ type => 'FeatureCollection', features => [ $kent, $surrey ] },
style => { weight => 2, fill => 0 }, bands => 'colours');
bands names a feature property that holds a list of colours (#rrggbb).
A polygon's outline is then drawn just inside its edge, not along the middle
of it, in a line of the width style gives. So where two polygons share a
border, each one's colour is on its own side: the border reads as a line twice
as wide, a different colour either side, and neither hides the other.
A polygon with several colours, for an area that belongs to more than one
group, gets a line of each, side by side: the first against the edge, each
further one further inside. A feature without the property, or with no colour
that can be used, is drawn as style says. Only polygons are banded; a line
or point takes the first colour.
The lines are cut to the inside of the polygon, which needs Leaflet's default SVG drawing. A map drawn on a canvas shows them uncut, along the middle of the edge, the first colour on top. A popup opens from the outline as before. Neighbours' lines meet exactly only where their shared border is the same in both polygons; outlines simplified one at a time leave small gaps or overlaps.
Examples
# Pre-parsed GeoJSON structure with style and popup property
$map->add_geojson(
{ type => 'FeatureCollection', features => \@features },
style => { color => '#ff0000', weight => 2, fillOpacity => 0.4 },
popup => 'name',
);
# Raw JSON string - decoded automatically
$map->add_geojson('{"type":"FeatureCollection","features":[]}');
# Multiple GeoJSON layers with different styles on the same map
$map->add_geojson(\%country_borders, style => { color => '#333333', fillOpacity => 0 });
$map->add_geojson(\%river_data, style => { color => '#0099ff', weight => 1 });
# County outlines the reader can turn on: hidden at first
$map->add_geojson(
{ type => 'FeatureCollection', features => \@counties },
style => { color => '#555555', weight => 1, fill => 0 },
popup => 'name',
name => 'County boundaries',
show => 0,
);
Add_Heatmap
Add a heatmap layer to the map.
$map->add_heatmap([[51.5, -0.1, 0.8], [51.6, -0.2, 0.5]], radius => 25);
Each point is [$lat, $lon] or [$lat, $lon, $intensity] (intensity: 0-1).
Requires the Leaflet.heat plugin (heatmap_js_url).
Returns 1 on success.
Api Specification
Input
points : arrayref of ([lat, lon] | [lat, lon, intensity])
radius : number default 25 (a value that is not a positive number uses the default)
blur : number default 15 (a value that is not a positive number uses the default)
Output
{ type => integer, value => 1 }
Messages
| Message | Meaning / Resolution |
|-----------------------------------------|-----------------------------------|
| add_heatmap: points must be an arrayref | First argument is not an arrayref |
Examples
# Basic heatmap - [lat, lon] per point
$map->add_heatmap([
[51.5074, -0.1278],
[51.6000, -0.2000],
[51.4000, 0.0000],
]);
# With intensity values (0..1) and custom radius/blur
$map->add_heatmap(
[ [51.5, -0.1, 0.9], [51.6, -0.2, 0.5], [51.4, 0.0, 0.2] ],
radius => 30,
blur => 20,
);
Add_Gpx
Add a GPX track to the map from a URL.
$map->add_gpx('https://example.com/track.gpx');
The map view is auto-fitted to the track bounds after loading.
Requires the leaflet-gpx plugin (gpx_js_url).
Returns 1 on success.
Api Specification
Input
url : string URL of the GPX file (required)
Output
{ type => integer, value => 1 }
Messages
| Message | Meaning / Resolution |
|--------------------------|--------------------------|
| add_gpx: url is required | No URL argument supplied |
Examples
# Add a GPX track from a public URL; the map auto-fits to its bounds
$map->add_gpx('https://example.com/route.gpx');
# Multiple tracks on the same map
$map->add_gpx('https://example.com/morning-run.gpx');
$map->add_gpx('https://example.com/evening-walk.gpx');
Add_Choropleth
Add a choropleth (data-driven colour fill) layer to the map.
$map->add_choropleth(
\@geojson_features,
{ England => 100, Scotland => 80, Wales => 60 },
key => 'name',
scale => ['#ffffcc', '#a1dab4', '#41b6c4', '#2c7fb8', '#253494'],
);
Colours are pre-computed in Perl and baked into the emitted JavaScript. No extra browser plugin is required. Returns 1 on success.
Api Specification
Input
features : arrayref of GeoJSON Feature hashrefs (required)
values : hashref { feature_property_value => numeric_value } (required)
key : string feature property to match against values (default: 'name')
scale : arrayref hex-colour strings low-to-high (default: 5-step YlGnBu)
Output
{ type => integer, value => 1 }
Messages
| Message | Meaning / Resolution |
|---------------------------------------------|-----------------------------------|
| add_choropleth: features must be an arrayref | First argument is not an arrayref |
| add_choropleth: values must be a hashref | Second argument is not a hashref |
Examples
# Default 5-step YlGnBu scale, key property "name"
$map->add_choropleth(
\@geojson_features,
{ England => 100, Scotland => 80, Wales => 60 },
);
# Custom 3-step scale and a different GeoJSON property as the key
$map->add_choropleth(
\@geojson_features,
{ England => 100, Scotland => 80, Wales => 60 },
key => 'country',
scale => ['#f7fbff', '#6baed6', '#08519c'],
);
# choropleth-only map - center() must be called explicitly
$map->center([54.0, -2.0]);
$map->add_choropleth(\@uk_features, \%population_by_region);
my ($head, $body) = $map->onload_render();
Center
Set the map centre to a given point.
$map->center([40.7128, -74.0060]);
$map->center($geo_object);
$map->center('Berlin, Germany');
Returns 1 on success, 0 if the point cannot be resolved or is out of range. An empty address also returns 0.
Api Specification
Input
point : arrayref [lat, lon] | object with latitude()/longitude() | string address
Output
{ type => integer, enum => [0, 1] }
Messages
| Message | Meaning / Resolution |
|----------------------------------------------------|---------------------------------|
| center(): usage: point => [ latitude, longitude ] | No point argument supplied |
| center(): point must have latitude and longitude | Arrayref has != 2 elements |
| center(): unknown point type: TYPE | Ref type has no lat/lon methods |
| Skipping invalid coordinate: (LAT, LON) | Warning: point is not numeric or is out of range; 0 is returned |
Examples
# Coordinate array
$map->center([40.7128, -74.0060]);
# Object that implements latitude()/longitude() (e.g. a Geo::Coder result)
$map->center($geocoder->geocode('Berlin, Germany'));
# String address resolved via the injected geocoder or Nominatim
$map->center('Eiffel Tower, Paris, France');
# Required when rendering without point markers (GeoJSON-only, choropleth, etc.)
$map->center([54.0, -2.0]);
$map->add_geojson(\%uk_regions, popup => 'name');
my ($head, $body) = $map->onload_render();
Zoom
Get or set the zoom level (0 = world, 19 = building).
$map->zoom(10);
my $z = $map->zoom();
Api Specification
Input
{ zoom => { type => integer, min => 0, max => 19, optional => 1 } }
Output
{ type => integer, min => 0, max => 19 }
Messages
| Message | Meaning / Resolution |
|------------------------------|-------------------------------------------|
| (Params::Validate::Strict) | zoom is not an integer or is out of range |
Examples
# Setter: store the zoom level
$map->zoom(14);
# Getter: retrieve the current level
my $level = $map->zoom();
print "Current zoom: $level\n"; # 14
# Setter return value equals the new level
my $confirmed = $map->zoom(10);
die 'unexpected' unless $confirmed == 10;
# Chain: set via new(), read back via zoom()
my $m = HTML::OSM->new(zoom => 6);
$m->zoom($m->zoom() + 2); # nudge up by 2
Onload_Render
Render the map and return a two-element list suitable for embedding in HTML.
my ($head_html, $body_html) = $map->onload_render();
$head_html contains the Leaflet CSS, JavaScript, and plugin assets.
Place it inside <head>...</head>.
$body_html contains the search box (unless search => 0), control
buttons, map <div>, and the initialisation <script>.
Place it inside <body>...</body> where the map should appear.
The rendered page provides:
- A Nominatim-powered search box that adds temporary markers.
Left out when
search => 0. - A "Clear search markers" button that removes those temporary markers,
leaving static markers (added via
add_marker) intact. Left out whensearch => 0. - A "Reset Map" button that returns the view to the initial centre and zoom,
or to every marker when
fit => 1. - A scale bar, when
scale => 1. - A key, when
legendhas entries, that lists only the groups in view.
Values that reach the object without going through new()'s checks (from a
config file or a clone) are checked again here. A zoom that is not an
integer from 0 to 19 is replaced by 12, and a width or height that is
not a CSS length (such as 600px, 100% or auto) is replaced by the
default. A max_zoom that is not an integer from 0 to 28 is ignored. Each
replacement gives a warning.
Api Specification
Input
(none - uses object state)
Output
{ type => list, elements => [string, string] }
Messages
| Message | Meaning / Resolution |
|--------------------------------------------------|---------------------------------------------|
| No map data provided | No markers, circle markers, GeoJSON, heatmap, GPX, or choropleth added yet |
| center() must be called when no point markers are provided | Non-marker-only render needs explicit centre |
| Skipping invalid coordinate: (LAT, LON) | Warning: a marker is not numeric or out of range; it is left off the map |
| onload_render: invalid nonce | nonce from a config file or clone is not base64 or base64url |
| onload_render: invalid zoom 'Z', using 12 | Warning: zoom from a config file or clone is out of range |
| onload_render: invalid max_zoom 'Z', ignoring it | Warning: max_zoom from a config file or clone is not an integer from 0 to 28 |
| onload_render: invalid width 'W', using 600px | Warning: width is not a CSS length |
| onload_render: invalid height 'H', using 400px | Warning: height is not a CSS length |
| onload_render: invalid legend_position 'P', using topright | Warning: legend_position from a config file or clone is not a corner |
| onload_render: legend entry N: ...; leaving it out of the key | Warning: a legend entry from a config file or clone is unusable |
| onload_render: legend must be an arrayref; leaving it out of the key | Warning: legend from a config file or clone is not an arrayref; no key is drawn |
| _fetch_coordinates: failed to decode Nominatim response: ERROR | Warning: Nominatim returned something that is not JSON; the marker is skipped |
| _fetch_coordinates: unrecognised geocoder result type: TYPE | Warning: the injected geocoder returned an unknown type; the marker is skipped |
Examples
# Minimal: one marker, embed in a CGI response
use HTML::OSM;
my $map = HTML::OSM->new(zoom => 12);
$map->add_marker([51.5074, -0.1278], html => 'London');
my ($head, $body) = $map->onload_render();
print "Content-Type: text/html\n\n";
print "<html><head>$head</head><body>$body</body></html>\n";
# Mixed layers: markers + GeoJSON, explicit center
$map->center([51.5, -0.1]);
$map->add_geojson(\%borough_data, popup => 'name', style => { color => '#333' });
$map->add_marker([51.5074, -0.1278], html => 'City of London');
my ($head_html, $body_html) = $map->onload_render();
# Template Toolkit integration
$tt->process('map.tt', {
map_head => scalar(($map->onload_render())[0]),
map_body => scalar(($map->onload_render())[1]),
});
Pseudocode
1. Gather all data layers; croak if none populated.
2. Geocode/validate each coordinate tuple; discard invalids with a warning.
A tuple with no coordinates and no address is discarded.
Check circle markers the same way.
Re-check zoom, max_zoom, width and height; fall back with a warning.
3. Determine map centre: caller-supplied > computed midpoint of the bounds
of the pin and circle markers. With fit and no caller centre, also
fit the view to those bounds, at most at zoom, on load and on reset.
Croak if neither is available.
4. Build <head>: Leaflet CSS + JS; inject cluster/heatmap/GPX plugin assets
only when the corresponding layer type is present.
5. Build <body>: search box and clear-search button (when search is on),
reset button, map <div>.
6. Initialise Leaflet map, tile layer (with maxZoom when max_zoom is set),
and the searchMarkers array when search is on.
7. Emit JS for each pin and circle marker (via one clusterGroup when
cluster is set), then the scale bar when scale is set, then the key
when legend has entries: its entries, the groups and where each
grouped marker is, redrawn on every moveend.
8. Emit JS for each GeoJSON, heatmap, GPX, and choropleth layer.
9. Attach event listeners: reset-view, and when search is on,
clear-search-markers and search-on-Enter.
10. Return ($head, $body).
Limitations
- Per-marker removal: Markers added via
add_marker()cannot yet be removed individually by clicking them. The "Clear search markers" button only removes markers added by the in-page Nominatim search box. - Clone validation: The clone path (
$obj->new(%overrides)) bypasses the Params::Validate::Strict schema so subclasses and internal callers can merge arbitrary state. Callers are responsible for passing valid overrides. - Config-file params unvalidated: Keys injected by
Object::Configure from a config file are not re-run through the schema, so
a malformed config file can introduce invalid types at runtime.
onload_render()checkszoom,max_zoom,widthandheightagain and HTML-escapes the CDN URLs, so a bad value cannot inject markup into the page. - One map per page: The rendered HTML uses fixed element IDs
(
map,search-box,clear-search-buttonandreset-button), so two maps on the same page will clash. - Clustered circle markers: With
cluster => 1, circle markers are grouped with the pin markers, so at low zoom levels a cluster count is shown in place of the circles' sizes. Leaveclusteroff for a bubble map whose sizes should always be visible. - Private-method encapsulation:
_fetch_coordinates,_validate, and_js_stringare named with a leading underscore by convention only. Using Sub::Private inenforcemode would make the contract explicit, but that module is not yet listed as a dependency to avoid breaking white-box tests int/mock.t. - Routing: Turn-by-turn routing (Leaflet Routing Machine / OSRM) is explicitly out of scope for this module and will not be added here.
Author
Nigel Horne, <njh at nigelhorne.com>
Bugs
Please report bugs at https://github.com/nigelhorne/HTML-OSM/issues.
See Also
- https://wiki.openstreetmap.org/wiki/API
- HTML::GoogleMaps::V3 - the interface this module mirrors for compatibility.
- https://leafletjs.com/
- Configure an Object at Runtime
- Test Dashboard
Support
This module is provided as-is without any warranty.
Please report problems and ask questions at https://github.com/nigelhorne/HTML-OSM/issues.
You can find documentation for this module with the perldoc command.
perldoc HTML::OSM
You can also look for information at MetaCPAN: https://metacpan.org/dist/HTML-OSM.
Todo
Allow per-marker removal via clicking on a marker.
Formal Specification
New
HTML_OSM
coordinates : iseq (ℝ x ℝ x S x S x (S ∪ {∅}))
zoom : Z
cluster : B
scale : B
legend : iseq LegendEntry
legend_position : {topright, topleft, bottomright, bottomleft}
----------------------------------------
ZOOM_MIN <= zoom <= ZOOM_MAX
LegendEntry
label : S | label ≠ ''
colour : HexColour
radius : ℝ ∪ {∅} | radius = ∅ ∨ 0 < radius < 10^6
group : S ∪ {∅}
new ≙
params? : Params
osm! : HTML_OSM
----------------------------------------
osm!.zoom = params?.zoom ∨ 12
osm!.cluster = params?.cluster ∨ false
osm!.scale = params?.scale ∨ false
osm!.fit = params?.fit ∨ false
osm!.legend_position = params?.legend_position ∨ topright
Add_Marker
AddMarker
ΔHTML_OSM
point? : (ℝ x ℝ) ∪ S ∪ GeoObject
result! : {0, 1}
-----------------------------------------
result! = 1 ⟺ point? resolves to (lat, lon) ∈ ValidCoord
result! = 1 ⟹ coordinates' = coordinates ⌢ ⟨(lat, lon, label, icon, group)⟩
Add_Geojson
AddGeoJSON
ΔHTML_OSM
data? : GeoJSONStruct ∪ S
style? : StyleMap ∪ {∅}
popup? : S ∪ {∅}
name? : S ∪ {∅}
show? : 𝔹 ∪ {∅}
key? : LayerKey ∪ {∅}
-----------------------------------------
name? ≠ ∅ ⇒ name? ≠ ""
key? ≠ ∅ ⇒ #key?.entries ≥ 1 ∧ key?.position ∈ Corner
geojson' = geojson ⌢ ⟨{data, style, popup, name, show, key}⟩
Add_Heatmap
AddHeatmap
ΔHTML_OSM
points? : iseq (ℝ x ℝ x [0,1])
-----------------------------------------
heatmap_layers' = heatmap_layers ⌢ ⟨{points, radius, blur}⟩
Add_Gpx
AddGPX
ΔHTML_OSM
url? : S | url? ≠ ''
-----------------------------------------
gpx_tracks' = gpx_tracks ⌢ ⟨url?⟩
Add_Choropleth
AddChoropleth
ΔHTML_OSM
features? : iseq GeoFeature
values? : S --> ℝ
key? : S
scale? : iseq S
-----------------------------------------
Let min = min(ran values?), max = max(ran values?) ∪ {min+1}
∀ k ∈ dom values? •
color(k) = scale?[floor((values?(k)-min)/(max-min) * (#scale?-1))]
choropleth_layers' = choropleth_layers ⌢ ⟨{features, values, colors, key}⟩
Center
Center
ΔHTML_OSM
point? : (ℝ x ℝ) ∪ S ∪ GeoObject
result! : {0, 1}
-----------------------------------------
result! = 1 ⟺ point? resolves to (lat, lon) ∈ ValidCoord
result! = 1 ⟹ center' = (lat, lon)
Zoom
Zoom
ΔHTML_OSM
zoom? : Z ∪ {∅}
zoom! : Z
-----------------------------------------
zoom? ≠ ∅ ⟹ ZOOM_MIN <= zoom? <= ZOOM_MAX
zoom! = (zoom? ≠ ∅ ∧ zoom' = zoom?) ∨ zoom
Onload_Render
OnloadRender
HTML_OSM
head! : S
body! : S
-----------------------------------------
(#coordinates + #geojson + #heatmap_layers + #gpx_tracks + #choropleth_layers) > 0
center ≠ ∅ ∨ ∃ valid ∈ coordinates • valid ∈ ValidCoord
Let InView(b) = { m.group | m ∈ coordinates ∪ circle_markers • (m.lat, m.lon) ∈ b }
fit ∧ center = ∅ ⟹ the initial view contains every (m.lat, m.lon), at zoom ≤ zoom
∀ bounds b reached by a move or zoom •
listed(b) = ⟨ e ∈ legend | e.group = ∅ ∨ e.group ∈ InView(b) ⟩
License and Copyright
Copyright 2025-2026 Nigel Horne.
This program is released under the following licence: GPL2 If you use it, please let me know.