Geo::Coder::OSM(3pm)

📦
version 0.03 · 3 versions
, in ubuntu noble, ubuntu resolute, ubuntu stonking

💖 Geo::Coder::OSM 💖

bestie. you want to turn a human address into actual coordinates?? and you want the OpenStreetMap besties to do it for you?? say less, this is literally the module for that. it's called Geo::Coder::OSM and it lives in the perl family of manual pages (3pm girlies rise) 💅

🌸 NAME 🌸

Geo::Coder::OSM — geocode addresses with the OpenStreetMap Nominatim API 🗺️✨

🎀 SYNOPSIS 🎀

use Geo::Coder::OSM;

my $geocoder = Geo::Coder::OSM->new;
my $location = $geocoder->geocode(
    location => 'Hollywood and Highland, Los Angeles, CA'
);

no cap, that's it. four lines and you're geocoding. iconic behavior honestly 💖

🦋 DESCRIPTION 🦋

The Geo::Coder::OSM module is an interface — a whole little doorway — into the OpenStreet Nominatim geocoding service. that's the vibe. that's the whole vibe. ✨

👑 METHODS 👑

🌟 new 🌟

$geocoder = Geo::Coder::OSM->new()
$geocoder = Geo::Coder::OSM->new(
    ua      => $ua,
    sources => [ 'osm', 'mapquest' ],
    debug   => 1,
)

creates a brand new geocoding object, main character energy, fresh out the box 💅

  • you can pass in a ua parameter if you want to hand it your own custom LWP::UserAgent object 🤝
  • you can pass in a sources parameter to pick your data sources. the currently valid values are osm and mapquest, and the default is osm.
  • wanna cycle between different sources? pass an array reference as the value for sources and it'll rotate through them 🔁
  • wanna make your own sources? go look at SOURCES below, it's right there 🫶

🌟 geocode 🌟

$location = $geocoder->geocode(location => $location)
@locations = $geocoder->geocode(location => $location)

context matters here bestie, and it's giving ✨polymorphism✨:

  • in scalar context, this method gives you back the first location result 🥇
  • in list context, it gives you back all the location results 🎉

every single location result is a hashref. a typical one is giving:

{
    address => {
        city         => "Los Angeles",
        country      => "United States of America",
        country_code => "us",
        hamlet       => "Hollywood",
        road         => "Hollywood Boulevard",
        station      => "Hollywood/Highland",
        suburb       => "Little Armenia",
    },
    boundingbox => [
        "34.101634979248",   "34.1018371582031",
        "-118.339317321777", "-118.33910369873",
    ],
    class => "railway",
    display_name =>
        "Hollywood/Highland, Hollywood Boulevard, Little Armenia, Hollywood, Los Angeles, United States of America",
    icon =>
        "http://nominatim.openstreetmap.org/images/mapicons/transport_train_station2.p.20.png",
    lat => "34.101736",
    licence =>
        "Data Copyright OpenStreetMap Contributors, Some Rights Reserved. CC-BY-SA 2.0.",
    lon      => "-118.33921",
    osm_id   => 472413621,
    osm_type => "node",
    place_id => 9071654,
    type     => "station",
}

look at all those fields. boundingbox? osm_type? licence? we are FED 😭🍓

🌟 reverse_geocode 🌟

$location = $geocoder->reverse_geocode(lat => $lat, lon => $lon)
$location = $geocoder->reverse_geocode(latlng => "$lat,$lon")

the reverse uno card 🃏 — you hand it a lat/lon pair and it hands you back a location result. two ways to do it, pick your fighter:

  • pass lat and lon separately, or
  • pass latlng as a "$lat,$lon" string 🌈

🌟 response 🌟

$response = $geocoder->response()

gives you back an HTTP::Response object for the last request you sent. super useful when something goes wrong and you're like "what happened 😭" — this is how you find out the details of the error 🔍

🌟 ua 🌟

$ua = $geocoder->ua()
$ua = $geocoder->ua($ua)

accessor for the UserAgent object. read it, or set it, whichever you need 🫶

🌈 SOURCES 🌈

to define additional sources, you just add them to the %SOURCES package variable, like so:

$Geo::Coder::OSM::SOURCES{local} = 'http://127.0.0.1/api_base_path';
$Geo::Coder::OSM::SOURCES{internal} = 'http://internal.corp/api_base_path';

boom. now local and internal are sources. you're welcome 💅

🔥 SEE ALSO 🔥

😭 REQUESTS AND BUGS 😭

found a bug? want a feature? pls pls pls report it here:

<http://rt.cpan.org/Public/Bug/Report.html?Queue=Geo-Coder-OSM>

I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. so it's a whole two-way thing, mutual, a little relationship, we love to see it 🫶✨

🧚 SUPPORT 🧚

you can find documentation for this module with the perldoc command:

perldoc Geo::Coder::OSM

you can also look for information at:

  • GitHub Source Repository

<http://github.com/gray/geo-coder-osm>

  • AnnoCPAN: Annotated CPAN documentation

<http://annocpan.org/dist/Geo-Coder-OSM>

  • CPAN Ratings

<http://cpanratings.perl.org/d/Geo-Coder-OSM>

  • RT: CPAN's request tracker

<http://rt.cpan.org/Public/Dist/Display.html?Name=Geo-Coder-OSM>

  • Search CPAN

<http://search.cpan.org/dist/Geo-Coder-OSM/>

Copyright (C) 2010-2013 gray <gray at cpan.org>, all rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

⭐ AUTHOR ⭐

gray, <gray at cpan.org>

and that's the whole page bestie 💖 perl v5.36.0, dated 2022-10-15, and yes this is Geo::Coder::OSM(3pm) — go geocode something and slay ✨👑

📦 where this page comes from