/ 
WWW-3Taps-API-0.02
River stage zero No dependents
/ WWW::3Taps::API

NAME

WWW::3Taps::API

VERSION

Version 0.02

SYNOPSIS

use WWW::3Taps::API;

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

# $results = {
#   execTimeMs => 325,
#   numResults => 141087,
#   success => bless( do { \( my $o = 1 ) }, 'JSON::XS::Boolean' )
#   results    => [
#     {
#       category => "VAUT",
#       externalURL =>
#         "http://cgi.ebay.com/Ferrari-360-/8181818foo881818bar",
#       heading =>
# "Ferrari : 360 Coupe 2000 Ferrari 360 F1 Modena Coupe 20k Fresh Timing Belts",
#       location  => "LAX",
#       source    => "EBAYM",
#       timestamp => "2011/03/08 01:13:05 UTC"
#     },
#    ...


if ( $results->{success} ){
  foreach my $result (@{$results->{results}}) {
    print qq|<a href="$result->{externalURL}">$result->{heading}</a>\n|;
  }
}

DESCRIPTION

This module provides an Object Oriented interface to 3Taps(http://3taps.net) search API. See http://developers.3taps.net for a full description of the 3Taps API.

SUBROUTINES/METHODS

Search methods

search(%params)

use WWW::3Taps::API;

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

# {
#   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.

Status methods

update_status

my $api     = WWW::3Taps::API->new;
my $results = $api->status_update(
  postings => [
    {
      source     => "E_BAY",
      externalID => "3434399120",
      status     => "sent",
      timestamp  => "2011/12/21 01:13:28",
      attributes => { postKey => "3JE8VFD" }
    },
    {
      source     => "E_BAY",
      externalID => "33334399121",
      status     => "sent",
      timestamp  => "2011/12/21 01:13:28",
      attributes => { postKey => "3JE8VFF" }
    }
  ]
);

Send in status updates for postings

Parameters

postings

An array containing a list of hashrefs representing the posting status updates. Each entry in this array must contain a key representing the following:

status (required)

The status of the posting

externalID (required)

The ID of the posting in the source system.

source (required)

The 5 letter code of the source of this posting. (ex: CRAIG, E_BAY)

timestamp (optional)

The time that this status occured, in format YYYY/MM/DD hh:mm:dd, in UTC.

attributes (optional)

A hashref containing name/value pairs of attributes to associate with this status. (ex: postKey, errors)

Returns

The body of the response will consist of a hashref with two fields, code and message.

get_status

my $api     = WWW::3Taps::API->new;
my $results = $api->get_status(
  ids => [
    { source => 'CRAIG', externalID => 3434399120 },
    { source => 'CRAIG', externalID => 33334399121 }
  ]
);

# [
#   {
#     exists => bless( do { \( my $o = 0 ) }, 'JSON::XS::Boolean' ),
#     externalID => "3434399120",
#     source     => "CRAIG"
#   },
#   {
#     exists => bless( do { \( my $o = 1 ) }, 'JSON::XS::Boolean' ),
#     externalID => "3434399121",
#     history    => {
#       saved => [
#         {
#           attributes => {
#             batchKey => "BDBBTHF500",
#             postKey  => "BDBBTXQ"
#           },
#           errors    => undef,
#           timestamp => "2011-02-25T18:24:41Z"
#         }
#       ]
#     },
#     source => "CRAIG"
#   }
# ]

Get status history for postings

Parameters

ids

An array of hashrefs containing a key/value pair of two fields: "externalID" and "source". Each field will identify a posting to retrieve status for in this request.

Returns

An array of hashrefs, each representing a requested posting, each with the following fields

exists (boolean)

If false, the Status API has no history of the posting.

externalID (string)

The external ID of this requested posting.

source (string)

The 5 letter code of the source of this posting. (ex: E_BAY, CRAIG)

history (hashref)

The history hashref contains a number of fields, one for each "status" that has been recorded for the posting. Within each status field, the value is an array of status events for that status. For example, in the "found" status field, you would find a status event object for each time the posting was found. Each status event object can contain the following fields:

timestamp

The date that this status event was recorded, in UTC.

errors

An array of error hashrefs, each with two fields: "code" and "message".

attributes

An hashref holding a number of key/value pairs associated with this status event (ex: postKey)

system_status

my $api     = WWW::3Taps::API->new;
my $results = $api->status_system();

# { code => 200, message => "3taps is up and running!" }

Get the current system status.

Returns

A hashref with two fields, code and message.

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

For detailed developer info, see http://developers.3taps.net.

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.