LocationIq::Role - a Moose role for the LocationIQ
LocationIQ provides flexible enterprise-grade location based solutions. We work with developers, startups and enterprises worldwide serving billions of requests everyday. This page provides an overview of the technical aspects of our API and will help you get started.
Automatically generated by the OpenAPI Generator project:
- API version: 1.1.0
- Package version: 1.0.0
- Build package: org.openapitools.codegen.languages.PerlClientCodegen
This role is the only component of the library that uses Moose. See LocationIq::ApiFactory for non-Moosey usage.
The Perl Generator in the OpenAPI Generator project builds a library of Perl modules to interact with a web service defined by a OpenAPI Specification. See below for how to build the library.
This module provides an interface to the generated library. All the classes, objects, and methods (well, not quite *all*, see below) are flattened into this role.
package MyApp;
use Moose;
with 'LocationIq::Role';
package main;
my $api = MyApp->new({ tokens => $tokens });
my $pet = $api->get_pet_by_id(pet_id => $pet_id);
The library consists of a set of API classes, one for each endpoint. These APIs implement the method calls available on each endpoint.
Additionally, there is a set of "object" classes, which represent the objects returned by and sent to the methods on the endpoints.
An API factory class is provided, which builds instances of each endpoint API.
This Moose role flattens all the methods from the endpoint APIs onto the consuming class. It also provides methods to retrieve the endpoint API objects, and the API factory object, should you need it.
For documentation of all these methods, see AUTOMATIC DOCUMENTATION below.
In the normal case, the OpenAPI Spec will describe what parameters are required and where to put them. You just need to supply the tokens.
my $tokens = {
# basic
username => $username,
password => $password,
# oauth
access_token => $oauth_token,
# keys
$some_key => { token => $token,
prefix => $prefix,
in => $in, # 'head||query',
},
$another => { token => $token,
prefix => $prefix,
in => $in, # 'head||query',
},
...,
};
my $api = MyApp->new({ tokens => $tokens });
Note these are all optional, as are prefix
and in
, and depend on the API
you are accessing. Usually prefix
and in
will be determined by the code generator from
the spec and you will not need to set them at run time. If not, in
will
default to 'head' and prefix
to the empty string.
The tokens will be placed in a LLocationIq::Configuration instance as follows, but you don't need to know about this.
-
$cfg->{username}
String. The username for basic auth.
-
$cfg->{password}
String. The password for basic auth.
-
$cfg->{api_key}
Hashref. Keyed on the name of each key (there can be multiple tokens).
$cfg->{api_key} = { secretKey => 'aaaabbbbccccdddd', anotherKey => '1111222233334444', };
-
$cfg->{api_key_prefix}
Hashref. Keyed on the name of each key (there can be multiple tokens). Note not all api keys require a prefix.
$cfg->{api_key_prefix} = { secretKey => 'string', anotherKey => 'same or some other string', };
-
$cfg->{access_token}
String. The OAuth access token.
The generated code has the base_url
already set as a default value. This method
returns the current value of base_url
.
Returns an API factory object. You probably won't need to call this directly.
$self->api_factory('Pet'); # returns a LocationIq::PetApi instance
$self->pet_api; # the same
Most of the methods on the API are delegated to individual endpoint API objects
(e.g. Pet API, Store API, User API etc). Where different endpoint APIs use the
same method name (e.g. new()
), these methods can't be delegated. So you need
to call $api->pet_api->new()
.
In principle, every API is susceptible to the presence of a few, random, undelegatable method names. In practice, because of the way method names are constructed, it's unlikely in general that any methods will be undelegatable, except for:
new()
class_documentation()
method_documentation()
To call these methods, you need to get a handle on the relevant object, either
by calling $api->foo_api
or by retrieving an object, e.g.
$api->get_pet_by_id(pet_id => $pet_id)
. They are class methods, so
you could also call them on class names.
See the homepage https://openapi-generator.tech
for full details.
But briefly, clone the git repository, build the codegen codebase, set up your build
config file, then run the API build script. You will need git, Java 7 or 8 and Apache
maven 3.0.3 or better already installed.
The config file should specify the project name for the generated library:
{"moduleName":"WWW::MyProjectName"}
Your library files will be built under WWW::MyProjectName
.
$ git clone https://github.com/openapitools/openapi-generator
$ cd openapi-generator
$ mvn package
$ java -jar modules/openapi-generator-cli/target/openapi-generator-cli.jar generate \
-i [URL or file path to JSON OpenAPI API spec] \
-g perl \
-c /path/to/config/file.json \
-o /path/to/output/folder
Bang, all done. Run the autodoc
script in the bin
directory to see the API
you just built.
You can print out a summary of the generated API by running the included
autodoc
script in the bin
directory of your generated library. A few
output formats are supported:
Usage: autodoc [OPTION]
-w wide format (default)
-n narrow format
-p POD format
-H HTML format
-m Markdown format
-h print this help message
-c your application class
The -c
option allows you to load and inspect your own application. A dummy
namespace is used if you don't supply your own class.
Additional documentation for each class and method may be provided by the OpenAPI
spec. If so, this is available via the class_documentation()
and
method_documentation()
methods on each generated object class, and the
method_documentation()
method on the endpoint API classes:
my $cmdoc = $api->pet_api->method_documentation->{$method_name};
my $odoc = $api->get_pet_by_id->(pet_id => $pet_id)->class_documentation;
my $omdoc = $api->get_pet_by_id->(pet_id => $pet_id)->method_documentation->{method_name};
Each of these calls returns a hashref with various useful pieces of information.
To load the API packages:
use LocationIq::AutocompleteApi;
use LocationIq::BalanceApi;
use LocationIq::DirectionsApi;
use LocationIq::MatchingApi;
use LocationIq::MatrixApi;
use LocationIq::NearestApi;
use LocationIq::ReverseApi;
use LocationIq::SearchApi;
To load the models:
use LocationIq::Object::Address;
use LocationIq::Object::Balance;
use LocationIq::Object::Daybalance;
use LocationIq::Object::DirectionsDirections;
use LocationIq::Object::DirectionsDirectionsRoutes;
use LocationIq::Object::DirectionsMatching;
use LocationIq::Object::DirectionsMatrix;
use LocationIq::Object::DirectionsMatrixSources;
use LocationIq::Object::DirectionsNearest;
use LocationIq::Object::DirectionsNearestWaypoints;
use LocationIq::Object::Error;
use LocationIq::Object::Location;
use LocationIq::Object::Matchquality;
use LocationIq::Object::Namedetails;
Put the Perl SDK under the 'lib' folder in your project directory, then run the following
#!/usr/bin/perl
use lib 'lib';
use strict;
use warnings;
# load the API package
use LocationIq::AutocompleteApi;
use LocationIq::BalanceApi;
use LocationIq::DirectionsApi;
use LocationIq::MatchingApi;
use LocationIq::MatrixApi;
use LocationIq::NearestApi;
use LocationIq::ReverseApi;
use LocationIq::SearchApi;
# load the models
use LocationIq::Object::Address;
use LocationIq::Object::Balance;
use LocationIq::Object::Daybalance;
use LocationIq::Object::DirectionsDirections;
use LocationIq::Object::DirectionsDirectionsRoutes;
use LocationIq::Object::DirectionsMatching;
use LocationIq::Object::DirectionsMatrix;
use LocationIq::Object::DirectionsMatrixSources;
use LocationIq::Object::DirectionsNearest;
use LocationIq::Object::DirectionsNearestWaypoints;
use LocationIq::Object::Error;
use LocationIq::Object::Location;
use LocationIq::Object::Matchquality;
use LocationIq::Object::Namedetails;
# for displaying the API response data
use Data::Dumper;
use LocationIq::;
my $api_instance = LocationIq::->new(
# Configure API key authorization: key
api_key => {'key' => 'YOUR_API_KEY'},
# uncomment below to setup prefix (e.g. Bearer) for API key, if needed
#api_key_prefix => {'key' => 'Bearer'},
);
my $q = "Empire state"; # string | Address to geocode
my $normalizecity = 1; # int | For responses with no city value in the address section, the next available element in this order - city_district, locality, town, borough, municipality, village, hamlet, quarter, neighbourhood - from the address section will be normalized to city. Defaults to 1 for SDKs.
my $limit = 10; # int | Limit the number of returned results. Default is 10.
my $viewbox = "-132.84908,47.69382,-70.44674,30.82531"; # string | The preferred area to find search results. To restrict results to those within the viewbox, use along with the bounded option. Tuple of 4 floats. Any two corner points of the box - `max_lon,max_lat,min_lon,min_lat` or `min_lon,min_lat,max_lon,max_lat` - are accepted in any order as long as they span a real box.
my $bounded = 1; # int | Restrict the results to only items contained with the viewbox
my $countrycodes = "us"; # string | Limit search to a list of countries.
my $accept_language = "en"; # string | Preferred language order for showing search results, overrides the value specified in the Accept-Language HTTP header. Defaults to en. To use native language for the response when available, use accept-language=native
my $tag = "place"; # string | Restricts the autocomplete search results to elements of specific OSM class and type. Example - To restrict results to only class place and type city: tag=place:city, To restrict the results to all of OSM class place: tag=place
eval {
my $result = $api_instance->autocomplete(q => $q, normalizecity => $normalizecity, limit => $limit, viewbox => $viewbox, bounded => $bounded, countrycodes => $countrycodes, accept_language => $accept_language, tag => $tag);
print Dumper($result);
};
if ($@) {
warn "Exception when calling AutocompleteApi->autocomplete: $@\n";
}
All URIs are relative to https://eu1.locationiq.com/v1
Class | Method | HTTP request | Description |
---|---|---|---|
AutocompleteApi | autocomplete | GET /autocomplete.php | |
BalanceApi | balance | GET /balance.php | |
DirectionsApi | directions | GET /directions/driving/{coordinates} | Directions Service |
MatchingApi | matching | GET /matching/driving/{coordinates} | Matching Service |
MatrixApi | matrix | GET /matrix/driving/{coordinates} | Matrix Service |
NearestApi | nearest | GET /nearest/driving/{coordinates} | Nearest Service |
ReverseApi | reverse | GET /reverse.php | Reverse Geocoding |
SearchApi | search | GET /search.php | Forward Geocoding |
- LocationIq::Object::Address
- LocationIq::Object::Balance
- LocationIq::Object::Daybalance
- LocationIq::Object::DirectionsDirections
- LocationIq::Object::DirectionsDirectionsRoutes
- LocationIq::Object::DirectionsMatching
- LocationIq::Object::DirectionsMatrix
- LocationIq::Object::DirectionsMatrixSources
- LocationIq::Object::DirectionsNearest
- LocationIq::Object::DirectionsNearestWaypoints
- LocationIq::Object::Error
- LocationIq::Object::Location
- LocationIq::Object::Matchquality
- LocationIq::Object::Namedetails
- Type: API key
- API key parameter name: key
- Location: URL query string