/ 
WWW-3Taps-API-0.01
/ WWW::3Taps::API

NAME

WWW::3Taps::API

VERSION

Version 0.01

SYNOPSIS

use WWW::3Taps::API;

my $api = WWW::3Taps::API->new();
my $results = $api->search( location => 'LAX+OR+NYC', category => 'VAUT' );
my $count = $api->count( location => 'LAX+OR+NYC', category => 'VAUT' );

SUBROUTINES/METHODS

search(%params)

my $api    = WWW::3Taps::API->new;
my $result = $api->search(
  location    => 'LAX+OR+NYC',
  category    => 'VAUT',
  annotations => '{"make":"porsche"}'
);

# {
#   execTimeMs => 7,
#   numResults => 0,
#   results    => [],
#   success    => 1
# }

The search method creates a new search request.

Parameters

rpp

The number of results to return for a synchonous search. If this is not specified, a maximum of ten postings will be returned at once. If this is set to -1, all matching postings will be returned at once.

page

The page number of the results to return for a synchronous search, where zero is the first page of results. If this is not specified, the most recent page of postings will be returned.

source

The 5-character source code a posting must have if is to be included in the list of search results.

category

The 4-character category code a posting must have if it is to be included in the list of search results. Note that multiple categories can be searched by passing in multiple category codes, separated by +OR+.

location

The 3-character location code a posting must have if it is to be included in the list of search results. Note that multiple locations can be searched by passing in multiple location codes, separated by +OR+.

heading

A string which must occur within the heading of the posting if it is to be included in the list of search results.

body

A string which must occur within the body of the posting if it is to be included in the list of search results.

text

A string which must occur in either the heading or the body of the posting if it is to be included in the list of search results.

poster

The user ID of the person who created the posts. If this is specified, only postings created by the specified user will be included in the list of search results

externalID

A string which must match the "externalID" field for a posting if it is to be included in the list of search results.

start

(YYYY-MM-DD HH:MM:SS) This defines the desired starting timeframe for the search query. Only postings with a timestamp greater than or equal to the given value will be included in the list of search results. Note: all times in 3taps are in UTC.

end

(YYYY-MM-DD HH:MM:SS) This defines the desired ending timeframe for the search query. Only postings with a timestamp less than or equal to the given value will be included in the list of search results. Note: all times in 3taps are in UTC.

annotations

A JSON encoded map of key/value pairs that a posting must have in annotations to be included in the list of search results

trustedAnnotations

A JSON encoded map of key/value pairs that a posting must have in trusted annotations to be included in the list of search results

retvals

A comma-separated list of the fields to return for each posting that matches the desired set of search criteria. The following field names are currently supported:

source
category
location
longitude
latitude
heading
body
images
externalURL
userID
timestamp
externalID
annotations
postKey

These fields match the fields with the same name as defined in the Posting API. If no retvals argument is supplied, the following list of fields will be returned by default:

category
location
heading
externalURL
timestamp

Returns

A hashref containing a decoded JSON object with the following fields:

success

If the search was a success, this will be true.

numResults

The total number of results found for this search.

execTimeMs

The amount of time it took 3taps to perform your search, in milliseconds.

error

If success is false, error will contain the error message

results

An array of posting objects, each containing the fields specified in retvals

count(%search_params)

my $api = WWW::3Taps::API->new;
my $result = $api->count( location => 'LAX', category => 'VAUT' );

# { count => 146725 }

Returns the number of items matching a given search. Note that this method accepts the same general parameters as the search method.

Parameters

Same as search method

Returns

A hashref with a single field, "count", holding the number of matches found for the given parameters.

best_match( $keyword )

my $api = WWW::3Taps::API->new;
my $result = $api->best_match('iPad');

# { category => undef, numResults => 50483160 }

Returns the 3taps category associated with the keywords, along with the number of results for that category in 3taps.

Parameters

keyword

One or more words to find the best match for.

Returns

A hashref with two fields: category and numResults, containing the 3taps category code and number of results found.

range(%search_params, fields => $fields)

my $api = WWW::3Taps::API->new;
my $result = $api->range( location => 'LAX', category => 'VAULT', fields => 'year,price');

# {
#   price => { max => 15000, min => 200 },
#   year  => { max => 2011, min => 1967 },
# }

Returns the minimum and maximum values currently in 3taps for the given fields, that match the given search parameters. The basic idea here is to provide developers with a method of determining sensible values for range-based filters. Note that this method accepts the same query parameters as the search method.

Parameters

fields

A comma-separated list of fields to retrieve the min and max values for. The Search API will look for the min and max values in fields and annotations.

Returns

A hashref with the min and max values for each field.

summary( %search_params, dimension => $dimension)

my $api = WWW::3Taps::API->new;
my $result = $api->summary( text => 'toyota', dimension => 'source');

# {
#   execTimeMs => 360,
#   totals => {
#     "37SIG" => 0,
#     "3TAPS" => 0,
#     "9-1-1" => 0,
#     "AMZON" => 0,
#     "CRAIG" => 184231,
#     "E_BAY" => 5221,
#      ...
#   }
# }

Returns the total number of postings found in 3taps, across the given dimension, that match the given search query parameters. For example, searching for "text=toyota" across "dimension=source" would return a list of all sources in 3taps, along with the number of postings matching the search "text=toyota" in that source. All search query parameters are supported. You may currently search across dimensions source, category, and location. At this time, category will only search across top level categories, and location is limited to our top 10 metro areas.

Parameters

dimension

The dimension to summarize across: source, category, or location.

Returns

A hashref with the following fields:

totals

A decoded JSON object with one field for each member of the dimension, along with the total found (matching the search query) in that dimension.

execTimeMs

The number of milliseconds it took 3taps to retrieve this information for you.

AUTHOR

Eden Cardim, <edencardim at gmail.com>

BUGS

Please report any bugs or feature requests to bug-www-3taps-api at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=WWW-3Taps-API. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc WWW::3Taps::API

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

Copyright 2011 Eden Cardim

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.