{"id":15478412,"url":"https://github.com/nigelhorne/geo-geonames","last_synced_at":"2026-02-24T19:34:23.120Z","repository":{"id":59149722,"uuid":"501638371","full_name":"nigelhorne/Geo-GeoNames","owner":"nigelhorne","description":"Perform geographical queries using GeoNames Web Services","archived":false,"fork":false,"pushed_at":"2024-09-02T23:17:27.000Z","size":242,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-10-19T03:22:37.107Z","etag":null,"topics":["cpan-module","geocode","geocoder","geocoding","geolocation","geonames","perl","perl5-module"],"latest_commit_sha":null,"homepage":"https://www.geonames.org","language":"Perl","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","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":"2022-06-09T12:12:23.000Z","updated_at":"2024-09-02T23:17:30.000Z","dependencies_parsed_at":"2024-04-10T21:29:46.217Z","dependency_job_id":"f550d425-0d70-4d7c-b95e-64f634b38c6c","html_url":"https://github.com/nigelhorne/Geo-GeoNames","commit_stats":{"total_commits":216,"total_committers":10,"mean_commits":21.6,"dds":"0.30092592592592593","last_synced_commit":"a5577dc93c822ff75269a294a4745e82b4beb02a"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nigelhorne%2FGeo-GeoNames","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nigelhorne%2FGeo-GeoNames/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nigelhorne%2FGeo-GeoNames/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nigelhorne%2FGeo-GeoNames/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nigelhorne","download_url":"https://codeload.github.com/nigelhorne/Geo-GeoNames/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241726753,"owners_count":20009968,"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-module","geocode","geocoder","geocoding","geolocation","geonames","perl","perl5-module"],"created_at":"2024-10-02T04:04:03.809Z","updated_at":"2026-02-24T19:34:23.114Z","avatar_url":"https://github.com/nigelhorne.png","language":"Perl","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NAME\n\nGeo::GeoNames - Perform geographical queries using GeoNames Web Services\n\n# VERSION\n\nVersion 1.15\n\n# SYNOPSIS\n\n        use Geo::GeoNames;\n        my $geo = Geo::GeoNames-\u003enew(username =\u003e $ENV{'GEONAME_USER'});\n\n        # make a query based on placename\n        my $result = $geo-\u003esearch(q =\u003e 'Fredrikstad', maxRows =\u003e 2);\n\n        # print the first result\n        print ' Name: ', $result-\u003e[0]-\u003e{name}, \"\\n\";\n        print ' Longitude: ', $result-\u003e[0]-\u003e{lng}, \"\\n\";\n        print ' Latitude: ', $result-\u003e[0]-\u003e{lat}, \"\\n\";\n\n        # Make a query based on postcode\n        $result = $geo-\u003epostalcode_search(\n                postalcode =\u003e '1630', maxRows =\u003e 3, style =\u003e 'FULL'\n        );\n\n# DESCRIPTION\n\nBefore you start, get a free GeoNames account and enable it for\naccess to the free web service:\n\n- Get an account\n\n    Go to [http://www.geonames.org/login](http://www.geonames.org/login)\n\n- Respond to the email\n- Login and enable your account for free access\n\n    [http://www.geonames.org/enablefreewebservice](http://www.geonames.org/enablefreewebservice)\n\nProvides a perl interface to the webservices found at\n[http://api.geonames.org](http://api.geonames.org). That is, given a given placename or\npostalcode, the module will look it up and return more information\n(longitude, latitude, etc) for the given placename or postalcode.\nWikipedia lookups are also supported. If more than one match is found,\na list of locations will be returned.\n\n## ua\n\nAccessor method to get and set UserAgent object used internally. You\ncan call _env\\_proxy_ for example, to get the proxy information from\nenvironment variables:\n\n    $geo_coder-\u003eua()-\u003eenv_proxy(1);\n\nYou can also set your own User-Agent object:\n\n    use LWP::UserAgent::Throttled;\n    $geo_coder-\u003eua(LWP::UserAgent::Throttled-\u003enew());\n\n# SUBROUTINES/METHODS\n\n- new\n\n            $geo = Geo::GeoNames-\u003enew( username =\u003e '...' );\n            $geo = Geo::GeoNames-\u003enew( username =\u003e '...', url =\u003e $url );\n\n    Constructor for Geo::GeoNames. It returns a reference to an\n    Geo::GeoNames object. You may also pass the url of the webservices to\n    use. The default value is [http://api.geonames.org](http://api.geonames.org) and is the only url,\n    to my knowledge, that provides the services needed by this module. The\n    username parameter is required.\n\n- username( $username )\n\n    With a single argument, set the GeoNames username and return that\n    username. With no arguments, return the username.\n\n- default\\_ua\n\n    Returns the default UserAgent used a Mojo::UserAgent object that\n    carps on errors.\n\n- default\\_url\n\n    Returns `http://api.geonames.org`.\n\n- url( $url )\n\n    With a single argument, set the GeoNames url and return that\n    url. With no arguments, return the url.\n\n- geocode( $placename )\n\n    This method is just an easy access to search. It is the same as\n    saying:\n\n            $geo-\u003esearch( q =\u003e $placename );\n\n- search( arg =\u003e $arg )\n\n    Searches for information about a placename. Valid names for **arg** are\n    as follows:\n\n            q               =\u003e $placename\n            name            =\u003e $placename\n            name_equals     =\u003e $placename\n            maxRows         =\u003e $maxrows\n            startRow        =\u003e $startrow\n            country         =\u003e $countrycode\n            continentCode   =\u003e $continentcode\n            adminCode1      =\u003e $admin1\n            adminCode2      =\u003e $admin2\n            adminCode3      =\u003e $admin3\n            fclass          =\u003e $fclass\n            featureClass    =\u003e $fclass,\n            featureCode     =\u003e $code\n            lang            =\u003e $lang\n            type            =\u003e $type\n            style           =\u003e $style\n            isNameRequired  =\u003e $isnamerequired\n            tag             =\u003e $tag\n            name_startsWith =\u003e $name_startsWith\n            countryBias     =\u003e $countryBias\n            cities          =\u003e $cities\n            operator        =\u003e $operator\n            searchlang      =\u003e $searchlang\n            charset         =\u003e $charset\n            fuzzy           =\u003e $fuzzy\n            north           =\u003e $north\n            west            =\u003e $west\n            east            =\u003e $east\n            south           =\u003e $south\n            orderby         =\u003e $orderby\n\n    One, and only one, of **q**, **name**, **name\\_equals**, or **name\\_startsWith** must be\n    supplied to this method.\n\n    fclass is deprecated.\n\n    For a thorough description of the arguments, see\n    [http://www.geonames.org/export/geonames-search.html](http://www.geonames.org/export/geonames-search.html)\n\n- find\\_nearby\\_placename( arg =\u003e $arg )\n\n    Reverse lookup for closest placename to a given coordinate. Valid\n    names for **arg** are as follows:\n\n            lat     =\u003e $lat\n            lng     =\u003e $lng\n            radius  =\u003e $radius\n            style   =\u003e $style\n            maxRows =\u003e $maxrows\n\n    Both **lat** and **lng** must be supplied to this method.\n\n    For a thorough descriptions of the arguments, see\n    [http://www.geonames.org/export](http://www.geonames.org/export)\n\n- find\\_nearest\\_address(arg =\u003e $arg)\n\n    Reverse lookup for closest address to a given coordinate. Valid names\n    for **arg** are as follows:\n\n            lat =\u003e $lat\n            lng =\u003e $lng\n\n    Both **lat** and **lng** must be supplied to this method.\n\n    For a thorough descriptions of the arguments, see\n    [http://www.geonames.org/maps/reverse-geocoder.html](http://www.geonames.org/maps/reverse-geocoder.html)\n\n    US only.\n\n- find\\_nearest\\_intersection(arg =\u003e $arg)\n\n    Reverse lookup for closest intersection to a given coordinate. Valid\n    names for **arg** are as follows:\n\n            lat =\u003e $lat\n            lng =\u003e $lng\n\n    Both **lat** and **lng** must be supplied to this method.\n\n    For a thorough descriptions of the arguments, see\n    [http://www.geonames.org/maps/reverse-geocoder.html](http://www.geonames.org/maps/reverse-geocoder.html)\n\n    US only.\n\n- find\\_nearby\\_streets(arg =\u003e $arg)\n\n    Reverse lookup for closest streets to a given coordinate. Valid names\n    for **arg** are as follows:\n\n            lat =\u003e $lat\n            lng =\u003e $lng\n\n    Both **lat** and **lng** must be supplied to this method.\n\n    For a thorough descriptions of the arguments, see\n    [http://www.geonames.org/maps/reverse-geocoder.html](http://www.geonames.org/maps/reverse-geocoder.html)\n\n    US only.\n\n- postalcode\\_search(arg =\u003e $arg)\n\n    Searches for information about a postalcode. Valid names for **arg**\n    are as follows:\n\n            postalcode =\u003e $postalcode\n            placename  =\u003e $placename\n            country    =\u003e $country\n            maxRows    =\u003e $maxrows\n            style      =\u003e $style\n\n    One, and only one, of **postalcode** or **placename** must be supplied\n    to this method.\n\n    For a thorough description of the arguments, see\n    [http://www.geonames.org/export](http://www.geonames.org/export)\n\n- find\\_nearby\\_postalcodes(arg =\u003e $arg)\n\n    Reverse lookup for postalcodes. Valid names for **arg** are as follows:\n\n            lat     =\u003e $lat\n            lng     =\u003e $lng\n            radius  =\u003e $radius\n            maxRows =\u003e $maxrows\n            style   =\u003e $style\n            country =\u003e $country\n\n    Both **lat** and **lng** must be supplied to this method.\n\n    For a thorough description of the arguments, see\n    [http://www.geonames.org/export](http://www.geonames.org/export)\n\n- postalcode\\_country\\_info\n\n    Returns a list of all postalcodes found on GeoNames. This method\n    takes no arguments.\n\n- country\\_info(arg =\u003e $arg)\n\n    Returns country information. Valid names for **arg** are as follows:\n\n            country =\u003e $country\n            lang    =\u003e $lang\n\n    For a thorough description of the arguments, see\n    [http://www.geonames.org/export](http://www.geonames.org/export)\n\n- find\\_nearby\\_wikipedia(arg =\u003e $arg)\n\n    Reverse lookup for Wikipedia articles. Valid names for **arg** are as\n    follows:\n\n            lat     =\u003e $lat\n            lng     =\u003e $lng\n            radius  =\u003e $radius\n            maxRows =\u003e $maxrows\n            lang    =\u003e $lang\n            country =\u003e $country\n\n    Both **lat** and **lng** must be supplied to this method.\n\n    For a thorough description of the arguments, see\n    [http://www.geonames.org/export](http://www.geonames.org/export)\n\n- find\\_nearby\\_wikipedia\\_by\\_postalcode(arg =\u003e $arg)\n\n    Reverse lookup for Wikipedia articles. Valid names for **arg** are as\n    follows:\n\n            postalcode =\u003e $postalcode\n            country    =\u003e $country\n            radius     =\u003e $radius\n            maxRows    =\u003e $maxrows\n\n    Both **postalcode** and **country** must be supplied to this method.\n\n    For a thorough description of the arguments, see\n    [http://www.geonames.org/export](http://www.geonames.org/export)\n\n- wikipedia\\_search(arg =\u003e $arg)\n\n    Searches for Wikipedia articles. Valid names for **arg** are as\n    follows:\n\n            q       =\u003e $placename\n            maxRows =\u003e $maxrows\n            lang    =\u003e $lang\n            title   =\u003e $title\n\n    **q** must be supplied to this method.\n\n    For a thorough description of the arguments, see\n    [http://www.geonames.org/export](http://www.geonames.org/export)\n\n- wikipedia\\_bounding\\_box(arg =\u003e $arg)\n\n    Searches for Wikipedia articles. Valid names for **arg** are as\n    follows:\n\n            south   =\u003e $south\n            north   =\u003e $north\n            east    =\u003e $east\n            west    =\u003e $west\n            lang    =\u003e $lang\n            maxRows =\u003e $maxrows\n\n    **south**, **north**, **east**, and **west** and must be supplied to this method.\n\n    For a thorough description of the arguments, see\n    [http://www.geonames.org/export](http://www.geonames.org/export)\n\n- cities(arg =\u003e $arg)\n\n    Returns a list of cities and placenames within the bounding box.\n    Valid names for **arg** are as follows:\n\n            south   =\u003e $south\n            north   =\u003e $north\n            east    =\u003e $east\n            west    =\u003e $west\n            lang    =\u003e $lang\n            maxRows =\u003e $maxrows\n\n    **south**, **north**, **east**, and **west** and must be supplied to this method.\n\n    For a thorough description of the arguments, see\n    [http://www.geonames.org/export](http://www.geonames.org/export)\n\n- country\\_code(arg =\u003e $arg)\n\n    Return the country code for a given point. Valid names for **arg** are\n    as follows:\n\n            lat    =\u003e $lat\n            lng    =\u003e $lng\n            radius =\u003e $radius\n            lang   =\u003e $lang\n\n    Both **lat** and **lng** must be supplied to this method.\n\n    For a thorough description of the arguments, see\n    [http://www.geonames.org/export](http://www.geonames.org/export)\n\n- earthquakes(arg =\u003e $arg)\n\n    Returns a list of cities and placenames within the bounding box.\n    Valid names for **arg** are as follows:\n\n            south        =\u003e $south\n            north        =\u003e $north\n            east         =\u003e $east\n            west         =\u003e $west\n            date         =\u003e $date\n            minMagnitude =\u003e $minmagnitude\n            maxRows      =\u003e $maxrows\n\n    **south**, **north**, **east**, and **west** and must be supplied to this method.\n\n    For a thorough description of the arguments, see\n    [http://www.geonames.org/export](http://www.geonames.org/export)\n\n- find\\_nearby\\_weather(arg =\u003e $arg)\n\n    Return the country code for a given point. Valid names for **arg** are\n    as follows:\n\n            lat =\u003e $lat\n            lng =\u003e $lng\n\n    Both **lat** and **lng** must be supplied to this method.\n\n    For a thorough description of the arguments, see\n    [http://www.geonames.org/export](http://www.geonames.org/export)\n\n- get(arg =\u003e $arg)\n\n    Returns information about a given place based on a geonameId.\n\n            geonameId  =\u003e $geonameId\n            lang       =\u003e $lang\n            style      =\u003e $style (Seems to be ignored, although documented)\n\n    **geonamesId** must be supplied to this method. **lang** and **style** are optional.\n\n    For a thorough description of the arguments, see\n    [http://www.geonames.org/export](http://www.geonames.org/export)\n\n- hierarchy(arg =\u003e $arg)\n\n    Returns all GeoNames higher up in the hierarchy of a place based on a geonameId.\n\n        geonameId =\u003e $geonameId\n        style     =\u003e $style (Not documented, but seems to be respected)\n\n    **geonamesId** must be supplied to this method. **style** is optional.\n\n    For a thorough description of the arguments, see\n    [http://www.geonames.org/export/place-hierarchy.html#hierarchy](http://www.geonames.org/export/place-hierarchy.html#hierarchy)\n\n- children(arg =\u003e $arg)\n\n    Returns the children (admin divisions and populated places) for a given geonameId.\n\n        geonameId =\u003e $geonameId\n        style     =\u003e $style (Not documented, but seems to be respected)\n\n    **geonamesId** must be supplied to this method. **style** is optional.\n\n    For a thorough description of the arguments, see\n    [https://www.geonames.org/export/place-hierarchy.html](https://www.geonames.org/export/place-hierarchy.html)\n\n# RETURNED DATASTRUCTURE\n\nThe datastructure returned from methods in this module is an array of\nhashes. Each array element contains a hash which in turn contains the\ninformation about the placename/postalcode.\n\nFor example, running the statement\n\n        my $result = $geo-\u003esearch(\n                q =\u003e \"Fredrikstad\", maxRows =\u003e 3, style =\u003e \"FULL\"\n                );\n\nyields the result:\n\n        $VAR1 = {\n                'population' =\u003e {},\n                'lat' =\u003e '59.2166667',\n                'elevation' =\u003e {},\n                'countryCode' =\u003e 'NO',\n                'adminName1' =\u003e \"\\x{d8}stfold\",\n                'fclName' =\u003e 'city, village,...',\n                'adminCode2' =\u003e {},\n                'lng' =\u003e '10.95',\n                'geonameId' =\u003e '3156529',\n                'timezone' =\u003e {\n                        'dstOffset' =\u003e '2.0',\n                        'content' =\u003e 'Europe/Oslo',\n                        'gmtOffset' =\u003e '1.0'\n                        },\n                'fcode' =\u003e 'PPL',\n                'countryName' =\u003e 'Norway',\n                'name' =\u003e 'Fredrikstad',\n                'fcodeName' =\u003e 'populated place',\n                'alternateNames' =\u003e 'Frederikstad,Fredrikstad,Fredrikstad kommun',\n                'adminCode1' =\u003e '13',\n                'adminName2' =\u003e {},\n                'fcl' =\u003e 'P'\n                };\n\nThe elements in the hashes depends on which **style** is passed to the\nmethod, but will always contain **name**, **lng**, and **lat** except for\npostalcode\\_country\\_info(), find\\_nearest\\_address(),\nfind\\_nearest\\_intersection(), and find\\_nearby\\_streets().\n\n# BUGS\n\nThis module is provided as-is without any warranty.\n\nNot a bug, but the GeoNames services expects placenames to be UTF-8\nencoded, and all data received from the webservices are also UTF-8 encoded.\nSo make sure that strings are encoded/decoded based on the correct encoding.\n\nPlease report any bugs found or feature requests through GitHub issues\n[https://github.com/nigelhorne/Geo-GeoNames/issues](https://github.com/nigelhorne/Geo-GeoNames/issues).\nor\n`bug-geo-geonamnes at rt.cpan.org`,\nor through the web interface at\n[http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Geo-GeoNames](http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Geo-GeoNames).\nI will be notified, and then you'll\nautomatically be notified of progress on your bug as I make changes.\n\n# SEE ALSO\n\n- Test coverage report: [https://nigelhorne.github.io/Geo-GeoNames/coverage/](https://nigelhorne.github.io/Geo-GeoNames/coverage/)\n- [http://www.geonames.org/export](http://www.geonames.org/export)\n- [http://www.geonames.org/export/ws-overview.html](http://www.geonames.org/export/ws-overview.html)\n\n# SOURCE AVAILABILITY\n\nThe source code for this module is available from Github\nat [https://github.com/nigelhorne/Geo-GeoNames](https://github.com/nigelhorne/Geo-GeoNames).\n\n# AUTHOR\n\nPer Henrik Johansen, `\u003cper.henrik.johansen@gmail.com\u003e`.\n\nPreviously maintained by brian d foy, `\u003cbrian.d.foy@gmail.com\u003e`\nand Nicolas Mendoza, `\u003cmendoza@pvv.ntnu.no\u003e`\n\nMaintained by Nigel Horne, `\u003cnjh at nigelhorne.com\u003e`\n\n# COPYRIGHT AND LICENSE\n\nCopyright (C) 2007-2021 by Per Henrik Johansen\nCopyright (C) 2022-2023 by Nigel Horne\n\nThis library is available under the Artistic License 2.0.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnigelhorne%2Fgeo-geonames","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnigelhorne%2Fgeo-geonames","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnigelhorne%2Fgeo-geonames/lists"}