WebService::Geocodio - A Perl interface to Geocod.io
version 0.05
use 5.014; use WebService::Geocodio; use WebService::Geocodio::Location; my $geo = WebService::Geocodio->new( api_key => $ENV{GEOCODIO_API_KEY} ); # Wrigley Field my $loc = WebService::Geocodio::Location->new( number => 1060, postdirection => 'W', street => 'Addison', suffix => 'Street', city => 'Chicago', state => 'IL', ); # Could add more than one thing here, even bare strings are OK # 20050 = zip code in Washington DC $geo->add_location($loc, '20050'); $geo->add_field('timezone'); # prints: # Chicago: 41.947205791667, -87.656316875, CST # Chicago: 41.947180613636, -87.657167363636, CST # Washington: 38.893311, -77.014647, EST map { say $_->city, ": ", $_->lat, ", ", $_->lng, ", " $_->fields->timezone->name } $geo->geocode();
This module is a fairly thin wrapper around the Geocod.io geocoding web service. This service currently supports US and many Canadian based addresses at the moment. Both forward and reverse geocoding is supported.
In my testing, the service is somewhat finicky about how addresses are presented and stored; please read the service API documentation thoroughly to make sure you're getting the best quality results from the service.
You will need to obtain a free API key to use this library.
All errors are fatal and reported by confess. If you want more graceful error handling, you might want to try using Try::Tiny.
confess
This is the geocod.io API key. It is required.
The list of locations you want to geocode. These can be bare strings (if you like) or you can use a fancy object like WebService::Geocodio::Location which will serialize itself to JSON automatically.
You may request the following fields be included in the results:
cd
Congressional District (for the current Congress). This will return detailed biographical information about the Senators and Congressional representative from this district in the current_legislators field which is structured as an array where the member of Congress is first, followed by the Senators for the entire state.
current_legislators
It's possible there may be overlaps in a given location, so this field is structured as an array since there may be 2 or more possible districts for a given location. See the official docs for more information.
cd113
Congressional District (for the 113th Congress which ran through 2015)
cd114
Congressional District (for the 114th Congress which ran through 2017)
cd115
Congressional District (for the 115th Congress which runs through 2019)
stateleg
The state legislative divisions for this location. The results include both House and Senate, unless the location is unicameral like Nebraska or Washington D.C., then only a senate result is given.
timezone
The timezone of this location, UTC offset and whether it observes daylight saving time.
school
The unified or elementary/secondary school district identifiers for this location.
census
Appends various U.S. Census statistical codes to your lookup. See the API docs for more information about these codes and how they can be used with other census data sets.
This method takes one or more locations and stores it in the locations attribute.
Show the locations currently set for geocoding.
If you want to clear the current list of locations, use this method.
This method takes one or more fields to include in a result set. Valid fields are:
cd (current Congress)
Fields that do not match these valid names are silently discarded.
Send the current list of locations to the geocod.io service.
Returns undef if there are no locations stored.
In a list context, returns a list of WebService::Geocodio::Location objects. In a scalar context, returns an arrayref of WebService::Geocodio::Location objects. The list of objects is presented in descending order of accuracy.
Send the current list of latitude, longitude pairs to the geocod.io service.
In a list context, returns a list of WebService::Geocodio::Location objects. In scalar context, returns an arrayref of WebService::Geocodio::Location objects. The list of objects is presented in descending order of accuracy.
Mark Allen <mrallen1@yahoo.com>
This software is copyright (c) 2018 by Mark Allen.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install WebService::Geocodio, copy and paste the appropriate command in to your terminal.
cpanm
cpanm WebService::Geocodio
CPAN shell
perl -MCPAN -e shell install WebService::Geocodio
For more information on module installation, please visit the detailed CPAN module installation guide.