NAME

WWW::PlaceEngine - get PC's location information from PlaceEngine.

SYNOPSIS

 use WWW::PlaceEngine;
 
 my $wpl = WWW::PlaceEngine->new(
   ua     => $ua,            # LWP::UserAgent's object
   appkey => 'AppKey',       # Application Key
 );
 
 # Check PlaceEngine client exists or not.
 $wpl->check_rtagd() or die $wpl->err;
 
 # Get rtag data.
 my $rtag = $wpl->get_rtag() or die $wpl->err;
 
 my $time  = $wpl->t         # Time of measuring location
 my $numap = $wpl->numap     # Number of found APs
 
 # Get location data.
 my $loc = $wpl->decode_rtag($rtag) or die $wpl->err;
 
 my $lat   = $loc->{lat};    # Latitude
 my $long  = $loc->{long};   # Longitude
 my $addr  = $loc->{addr};   # Address
 my $floor = $loc->{floor};  # Floor
 my $range = $loc->{range};  # Degree of precision
 
 # Or, you can run all process at one method. 
 $loc = $wpl->get_location() or die $wpl->err;
 
 ## Get location from local DB
 $loc = $wpl->get_local_location() or die $wpl->err;
 
 # Get only latlon data from local DB
 my $lat   = $loc->{lat};    # Latitude
 my $long  = $loc->{long};   # Longitude

DESCRIPTION

This module get PC's location information from PlaceEngine client and API host. For PlaceEngine, See to http://www.placeengine.com/.

METHODS

new()

new( %options )

returns a WWW::PlaceEngine object.

 my $wpl = WWW::PlaceEngine->new();

new can take some options.

 my $wpl = WWW::PlaceEngine->new(ua => LWP::UserAgent->new, appkey => 'WRO4eQ....UgTWFw');

Following options are supported:

ua

appkey

PlaceEngine needs application key (appkey) to get location information from host. Application key is determined from application's name (like perl.exe), and you can get it form http://www.placeengine.com/appk . By default, appkey are set to appkey of perl.exe. You can change them to your own appkey by this option.

host

URL of PlaceEngine API host. http://www.placeengine.com/api by default.

rtagd URL of PlaceEngine client daemon. http://localhost:5448 by default.

ua()

ua( $ua )

get or set LWP::UserAgent's object by this method.

appkey()

appkey( $appkey )

get or set appkey by this method.

host()

host( $host )

get or set URL of PlaceEngine API host by this method.

rtagd()

rtagd( $rtagd )

get or set URL of PlaceEngine client daemon by this method.

rtag

get AP's electric field strength data (called rtag). This property will be set after run check_rtagd method.

numap

get found AP's number. This property will be set after run check_rtagd method.

t

get time of mesuring location. This property will be set after run check_rtagd method.

check_rtagd()

check PlaceEngine client is exist or not, and version of it. If PlaceEngine client is not exist or old version, this method return undef value. Error message can be checked by err method.

get_rtag()

get AP's electric field strength data (called rtag) from PlaceEngine client. And also, after execute this method, rtag, numap and t properties are set. If some error occurs, this method return undef value, and error message can be checked by err method.

decode_rtag([rtag],[time])

access to API host and decode rtag to from PC's location information. Argument rtag and time are optional, and if not given, rtag and t properties are used. This method returns hash reference of location data and it includes:

lat

Latitude.

long

Longitude.

addr

Address string.

range

Degree of precision (Unit is meter).

floor

Floor.

msg

Japanese message returned from PlaceEngine API host.

t

Time of mesuring location.

If some error occurs, this method return undef value, and error message can be checked by err method.

get_location()

run check_rtagd, get_rtag and decode_rtag methods in order. If some error occurs, this method return undef value, and error message can be checked by err method.

get_local_location()

ask location to local DB. This method is independent and cannot share rtag data with other methods. For example, even if you set old rtag data to rtag property, this method returns realtime location data.

 my $wpl = WWW::PlaceEngine->new();
 
 # Set yesterday's rtag data
 my $wpl->rtag($rtag_yesterday);
 
 # Get location from local DB
 my $loc = $wpl->get_local_location();
 
 # $loc is not yesterday's location but now location data.

If some error occurs, this method return undef value, and error message can be checked by err method.

err

returns error string if error occurs.

errcode

return error code if error occurs.

DEPENDENCIES

Readonly JSON

SEE ALSO

http://www.placeengine.com/

AUTHOR

OHTSUKA Ko-hei, <nene[at]kokogiko.net>

COPYRIGHT AND LICENSE

Copyright 2006-2007 by OHTSUKA Ko-hei

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