{"id":25415160,"url":"https://github.com/nigelhorne/html-osm","last_synced_at":"2026-04-29T01:32:23.216Z","repository":{"id":277719287,"uuid":"933290241","full_name":"nigelhorne/HTML-OSM","owner":"nigelhorne","description":"A simple wrapper around the OpenStreetMap API","archived":false,"fork":false,"pushed_at":"2025-04-02T11:51:39.000Z","size":70,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-14T23:45:33.182Z","etag":null,"topics":["cpan","cpan-module","leaflet","leaflet-map","leafletjs","openstreetmap","perl","perl5","perl5-module"],"latest_commit_sha":null,"homepage":"https://metacpan.org/pod/HTML::OSM","language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nigelhorne.png","metadata":{"files":{"readme":"README.md","changelog":"Changes","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-02-15T15:57:38.000Z","updated_at":"2025-04-02T11:51:42.000Z","dependencies_parsed_at":null,"dependency_job_id":"bce90862-8bc0-49b1-85e2-8f070367d3a4","html_url":"https://github.com/nigelhorne/HTML-OSM","commit_stats":null,"previous_names":["nigelhorne/html-osm"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nigelhorne%2FHTML-OSM","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nigelhorne%2FHTML-OSM/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nigelhorne%2FHTML-OSM/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nigelhorne%2FHTML-OSM/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nigelhorne","download_url":"https://codeload.github.com/nigelhorne/HTML-OSM/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250431091,"owners_count":21429415,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cpan","cpan-module","leaflet","leaflet-map","leafletjs","openstreetmap","perl","perl5","perl5-module"],"created_at":"2025-02-16T15:21:15.514Z","updated_at":"2026-04-29T01:32:23.210Z","avatar_url":"https://github.com/nigelhorne.png","language":"Perl","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NAME\n\nHTML::OSM - Generate an interactive OpenStreetMap with customizable coordinates and zoom level\n\n# VERSION\n\nVersion 0.09\n\n# SYNOPSIS\n\n`HTML::OSM` is a Perl module for generating an interactive map using OpenStreetMap (OSM) and Leaflet.\nThe module accepts a list of coordinates with optional labels and zoom level to create a dynamic HTML file containing an interactive map.\nThe generated map allows users to view marked locations, zoom, and search for locations using the Nominatim API.\n\n    use HTML::OSM;\n    my $map = HTML::OSM-\u003enew();\n    # ...\n\n    $map = HTML::OSM-\u003enew(\n        coordinates =\u003e [\n          [34.0522, -118.2437, 'Los Angeles'],\n          [undef, undef, 'Paris'],\n        ],\n        zoom =\u003e 14,\n    );\n    my ($head, $map_div) = $map-\u003eonload_render();\n\n- Caching\n\n    Identical geocode requests are cached (using [CHI](https://metacpan.org/pod/CHI) or a user-supplied caching object),\n    reducing the number of HTTP requests to the API and speeding up repeated queries.\n\n    This module leverages [CHI](https://metacpan.org/pod/CHI) for caching geocoding responses.\n    When a geocode request is made,\n    a cache key is constructed from the request.\n    If a cached response exists,\n    it is returned immediately,\n    avoiding unnecessary API calls.\n\n- Rate-Limiting\n\n    A minimum interval between successive API calls can be enforced to ensure that the API is not overwhelmed and to comply with any request throttling requirements.\n\n    Rate-limiting is implemented using [Time::HiRes](https://metacpan.org/pod/Time%3A%3AHiRes).\n    A minimum interval between API\n    calls can be specified via the `min_interval` parameter in the constructor.\n    Before making an API call,\n    the module checks how much time has elapsed since the\n    last request and,\n    if necessary,\n    sleeps for the remaining time.\n\n# SUBROUTINES/METHODS\n\n## new\n\n    $map = HTML::OSM-\u003enew(\n        coordinates =\u003e [\n          [37.7749, -122.4194, 'San Francisco'],\n          [40.7128, -74.0060, 'New York'],\n          [51.5074, -0.1278, 'London'],\n        ],\n        zoom =\u003e 10,\n    );\n\nCreates a new `HTML::OSM` object with the provided coordinates and optional zoom level.\n\n- `cache`\n\n    A caching object.\n    If not provided,\n    an in-memory cache is created with a default expiration of one hour.\n\n- `coordinates`\n\n    An array reference containing a list of coordinates.\n    Each entry should be an array with latitude, longitude, and an optional label, in the format:\n\n        [latitude, longitude, label, icon_url]\n\n    If latitude and/or longitude is undefined,\n    the label is taken to be a location to be added.\n    If no coordinates are provided, an error will be thrown.\n\n- `config_file`\n\n    Points to a configuration file which contains the parameters to `new()`.\n    The file can be in any common format,\n    including `YAML`, `XML`, and `INI`.\n    This allows the parameters to be set at run time.\n\n- `css_url`\n\n    Location of the CSS, default [https://unpkg.com/leaflet@1.9.4/dist/leaflet.css](https://unpkg.com/leaflet@1.9.4/dist/leaflet.css).\n\n- `geocoder`\n\n    An optional geocoder object such as [Geo::Coder::List](https://metacpan.org/pod/Geo%3A%3ACoder%3A%3AList) or [Geo::Coder::Free](https://metacpan.org/pod/Geo%3A%3ACoder%3A%3AFree).\n\n- `height`\n\n    Height (in pixels or using your own unit), the default is 400px.\n\n- `js_url`\n\n    Location of the JavaScript, default [https://unpkg.com/leaflet@1.9.4/dist/leaflet.js](https://unpkg.com/leaflet@1.9.4/dist/leaflet.js).\n\n- `min_interval`\n\n    Minimum number of seconds to wait between API requests.\n    Defaults to `0` (no delay).\n    Use this option to enforce rate-limiting.\n\n- `ua`\n\n    An object to use for HTTP requests.\n    If not provided, a default user agent is created.\n\n- `host`\n\n    The API host endpoint.\n    Defaults to [https://nominatim.openstreetmap.org/search](https://nominatim.openstreetmap.org/search).\n\n- `width`\n\n    Width (in pixels or using your own unit), the default is 600px.\n\n- zoom\n\n    An optional zoom level for the map, with a default value of 12.\n\n## add\\_marker\n\nAdd a marker to the map at the given point.\nA point can be a unique place name, like an address,\nan object that understands `latitude()` and `longitude()`,\nor a pair of coordinates passed in as an arrayref: `[ latitude, longitude ]`.\nWill return 0 if the point is not found and 1 on success.\n\nIt takes two optional arguments:\n\n- html\n\n    Add a popup info window as well.\n\n- icon\n\n    A url to the icon to be added.\n\n## center\n\nCenter the map at a given point.\n\n### INPUT\n\n    $point is an object that understands latitude() and longitude(), or a two element array\n\n    $point-\u003elatitude() - float (+/- 90 to 0), the latitude\n    $point-\u003elongitude() - float (+/- 180 to 0), the longitude\n\n### OUTPUT\n\nReturns 1 on success, 0 if the point could not be found.\n\n## zoom\n\nGet/set the new zoom level (0 is coarsest, 19 is the finest)\n\n    $map-\u003ezoom(10);\n\n### API SPECIFICATION\n\n#### INPUT\n\n    {\n      zoom =\u003e {\n        type =\u003e 'integer',\n        min =\u003e 0,\n        max =\u003e 19,\n        optional =\u003e 1\n      }\n    }\n\n#### OUTPUT\n\n    {\n      type =\u003e 'integer',\n      min =\u003e 0,\n      max =\u003e 19\n    }\n\n## onload\\_render\n\nRenders the map and returns a two element list.\nThe first element needs to be placed in the head section of your HTML document.\nThe second in the body where you want the map to appear.\n\n# AUTHOR\n\nNigel Horne, `\u003cnjh at nigelhorne.com\u003e`\n\n# BUGS\n\n# SEE ALSO\n\n- [https://wiki.openstreetmap.org/wiki/API](https://wiki.openstreetmap.org/wiki/API)\n- [HTML::GoogleMaps::V3](https://metacpan.org/pod/HTML%3A%3AGoogleMaps%3A%3AV3)\n\n    Much of the interface to `HTML::OSM` mimicks this for compatibility.\n\n- [https://leafletjs.com/](https://leafletjs.com/)\n\nYou can find documentation for this module with the perldoc command.\n\n    perldoc HTML::OSM\n\nYou can also look for information at:\n\n- MetaCPAN\n\n    [https://metacpan.org/dist/HTML-OSM](https://metacpan.org/dist/HTML-OSM)\n\n- RT: CPAN's request tracker\n\n    [https://rt.cpan.org/NoAuth/Bugs.html?Dist=HTML-OSM](https://rt.cpan.org/NoAuth/Bugs.html?Dist=HTML-OSM)\n\n- CPAN Testers' Matrix\n\n    [http://matrix.cpantesters.org/?dist=HTML-OSM](http://matrix.cpantesters.org/?dist=HTML-OSM)\n\n- CPAN Testers Dependencies\n\n    [http://deps.cpantesters.org/?module=HTML::OSM](http://deps.cpantesters.org/?module=HTML::OSM)\n\n# SUPPORT\n\nThis module is provided as-is without any warranty.\n\nPlease report any bugs or feature requests to `bug-html-osm at rt.cpan.org`,\nor through the web interface at\n[http://rt.cpan.org/NoAuth/ReportBug.html?Queue=HTML-OSM](http://rt.cpan.org/NoAuth/ReportBug.html?Queue=HTML-OSM).\nI will be notified, and then you'll\nautomatically be notified of progress on your bug as I make changes.\n\n## TODO\n\nAllow dynamic addition/removal of markers via user input.\n\n# LICENSE AND COPYRIGHT\n\nCopyright 2025-2026 Nigel Horne.\n\nThis program is released under the following licence: GPL2\nIf you use it,\nplease let me know.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnigelhorne%2Fhtml-osm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnigelhorne%2Fhtml-osm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnigelhorne%2Fhtml-osm/lists"}