Eden Cardim > WWW-3Taps-API > WWW::3Taps::API

Download:
WWW-3Taps-API-0.06.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  2
Open  0
View/Report Bugs
Module Version: 0.06   Source  

NAME ^

WWW::3Taps::API

VERSION ^

Version 0.05

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 and https://github.com/3taps/3taps-Perl-Client for the source repository.

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.

range(%search_params, fields => $fields)

  my $api = WWW::3Taps::API->new;
  my $result = $api->range( location => 'LAX', category => 'VAUT', 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->system_status();

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

Get the current system status.

Returns

A hashref with two fields, code and message.

Reference API ^

The Reference API provides a mechanism for accessing the standard "reference information" used by the 3taps system, including locations,

reference_location

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

  # $results = [
  #   {
  #     city        => "New York",
  #     cityRank    => 1,
  #     code        => "NYC",
  #     country     => "United States",
  #     countryRank => 1,
  #     latitude    => "40.6344",
  #     longitude   => "-74.2827",
  #     stateCode   => "NY",
  #     stateName   => "New York"
  #   },

  #   {
  #     city     => "Los Angeles",
  #     cityRank => 2,
  #     code     => "LAX",
  #     country  => "United
  #   States",
  #     countryRank => 1,
  #     latitude    => "33.9846",
  #     longitude   => "-118.112",
  #     stateCode   => "CA",
  #     stateName   => "California"
  #   }, # (...)
  # ]

Returns the 3taps locations. Note that you can request a single location by passing in the location code.

  my $results = $api->reference_location('NYC');

  # $results = [
  #   {
  #     city        => "New York",
  #     cityRank    => 1,
  #     code        => "NYC",
  #     country     => "United States",
  #     countryRank => 1,
  #     latitude    => "40.6344",
  #     longitude   => "-74.2827",
  #     stateCode   => "NY",
  #     stateName   => "New York"
  #   }
  # ];

Returns

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

code (string)

A unique 3-character code identifying this location within 3taps.

countryRank (integer)

A number that can optionally be used to sort the countries into a useful order in the UI (ie, to place the most popular countries at the top, and "Other" at the bottom).

country (string)

The name of the country this location is in.

cityRank (integer)

A number that can optionally be used to sort the cities within a country into a useful order (eg, to place the most popular cities at the top, and "Other" at the bottom).

city (string)

The name of the city this location is in.

stateCode (string)

A brief (usually two-letter) code for the state or region this location is in.

stateName (string)

The name of the state or region this location is in. This will be blank for countries which do not have states or regions.

hidden (boolean)

If true, this location should be hidden from the user-interface.

latitude (float)

The latitude of this location.

longitude (float)

The longitude of this location.

reference_category

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

  # $results = [
  #   { category => "Toys & Hobbies",   code => "STOY", group => "For Sale" },
  #   { category => "Tools",            code => "STOO", group => "For Sale" },
  #   { category => "Tickets",          code => "STIX", group => "For Sale" },
  #   { category => "Sports & Fitness", code => "SSNF", group => "For Sale" },
  #   { category => "Other Goods",      code => "SOTH", group => "For Sale" }
  # ];

Returns the 3taps categories. Note that you can request a single category by passing in the category code:

  my $results = $api->reference_category( code => 'VAUT', annotations => 1);

Parameters

code (string) (optional)

Code representing a category

annotations (boolean) (optional)

Set to false if you'd prefer to get the category data without annotations. Defaults to true.

Returns

An array of hashrefs representing categories containing the following fields

code (string)

A unique 4-character code identifying this category within 3taps.

group (string)

The name of the group of this category.

category (string)

The name of the category.

hidden (boolean)

If true, this category should be hidden from the user-interface.

annotations (arrayref)

An array of hashref representing annotations. Each annotation may have the following fields:

name (string)

The name of this annotation.

type (string)

The type of the annotation. Possible types currently include "string", "select" and "number".

options (arrayref)

Suggested values for the annotation. Each suggestion is an HASHREF that can contain two fields: value and subannotation. value will contain the string value of this option, while subannotation will contain an annotation HASHREF that can be applied to a posting or search if this option is selected.

reference_source

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

  # $results = [
  #   {
  #     code => "37SIG",
  #     logo_sm_url => "http://3taps.com/img/logos/37SIG37sig-fav.png",
  #     logo_url => "http://3taps.com/img/logos/37SIG37signals.png",
  #     name => "37signals"
  #   },
  #   {
  #     code => "3TAPS",
  #     logo_sm_url => "http://3taps.com/img/logos/3TAPS3taps-fav.png",
  #     logo_url => "http://3taps.com/img/logos/3TAPS3taps.png",
  #     name => "3taps"
  #   }, # (...)
  # ];

Returns the 3taps sources. Note that you can request a single source by passing in the source code

  my $results = $api->reference_source('E_BAY');

Returns

An array of hashrefs representing source objects and containing the following fields:

code (string)

A unique 5-character code identifying this source within 3taps.

name (string)

The name of the source.

logo_url (string)

The URL of the logo to use for this source in the UI.

logo_sm_url (string)

The URL of a smaller, square logo to use for this source in the UI.

reference_modified

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

Returns the time that the Reference API's data was updated for the given reference type.

Parameters

reference_type (string)

Can be "source", "category", or "location".

Returns

The date that the Reference API's data was last updated for the given reference type. Ex:

  2010-12-08 22:29:38 UTC

Posting API ^

The Posting API allows developers to store and retrieve postings in the 3taps system.

Posting Model

Before diving into the methods of the Posting API, let's first define the structure of the posting object. Note that fields marked REQUIRED will always be present in postings received from 3taps, and are required in all postings sent to 3taps.

postKey (string)

The unique identifier for the posting in the 3taps system. REQUIRED

location (string)

A 3-character code identifying the location of this posting.

category (string)

A 4-character code identifying the category of this posting.

source (string)

A 5-character code identifying the source of this posting. REQUIRED

heading (string)

A short (max 255 character) piece of text that summarizes the posting. Think of it as the "title" of the posting. REQUIRED

body (string)

The content of the posting.

latitude (float)

The latitude of the posting.

longitude (float)

The longitude of the posting.

language (string)

The language of the posting, represented by a 2-letter code conforming to the ISO 639-1 standard (english is "en").

price (string)

The price of the posting, if any. Price may also be used for compensation, or rent, in different contexts.

currency (string)

The currency of the price of the posting, represented by a 3-letter code conforming to the ISO 4217 standard (US dollars is "USD").

images (arrayref)

An arrayref of strings, each containing the URL of an image associated with the posting.

externalID (string)

The ID of this posting in its source system.

externalURL (string)

The URL of this posting on its source system.

accountName (string)

The name of the user that created the posting in the source system.

accountID (string)

The ID of the user that created the posting in the source system.

timestamp (date)

The time that the posting was created in the source system, in format 'YYYY/MM/DD hh:mm:dd', in UTC. REQUIRED

expiration (date)

The time that the posting should expire in the 3taps system, in format 'YYYY/MM/DD hh:mm:dd', in UTC. Note that if no expiration is specified, 3taps will expire the posting after one week.

indexed (date)

The time that the posting was indexed in threetaps, in format 'YYYY/MM/DD hh:mm:dd', in UTC.

annotations (hashref)

A set of searchable key/value pairs associated with this posting.

trustedAnnotations (hashref)

A set of searchable key/value pairs associated with this posting, limited to 3taps trusted annotations.

clickCount (integer)

The number of times a posting has been clicked on in the 3taps system.

posting_get

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

  # $results = {
  #   accountId   => undef,
  #   accountName => "shopping.power2",
  #   annotations => {
  #     ship_to_locations => { 0 => "Worldwide" },
  #     tags => [ "#eBay", "#forsale", "#jewelry", "#HKG" ]
  #   },
  #   body     => "Thisisamensbluesportswatch.",
  #   category => "SGJE"
  #   # (...)
  #   }

Returns information about a single posting.

Parameters

postKey (string)

The posting key for the desired posting.

Returns

A hashref representing a posting object with one or more fields outlined above in the posting model. If the posting is not found, a hashref containing two keys: "code" and "message" representing the error, is returned instead.

posting_create

  my $api     = WWW::3Taps::API->new;
  my $results = $api->posting_create(
    postings => [
      {
        annotations => {
          brand => "Specialized",
          color => "red"
        },
        body        => "Thisisatestpost.One.",
        category    => "SGBI",
        currency    => "USD",
        externalURL => "http://www.ebay.com",
        heading     => "TestPost1inBicyclesForSaleCategory",
        location    => "LAX",
        price       => "1.99",
        timestamp   => '20101130232514',
        source      => "E_BAY"
      }
    ]
  );

  # $result = [{postKey:"X73XFN"}]

Saves a new posting in 3taps.

Parameters

postings (arrayref)

An arrayref of hashref representing objects to be saved in 3taps, each with one or more fields outlined above in the posting model.

Returns

An arrayref with one entry for each posting that was supplied. Each entry will be an hashref with the following fields:

postKey (string)

The postKey generated for this posting.

error (hashref)

If there was an error saving the posting, the error field will contain a hashref with two keys: "code" and "message".

posting_update

  my $api     = WWW::3Taps::API->new;
  my $results = $api->posting_update(
    postings => [
      [ 'X73XFP', { price       => '20.00' } ],
      [ 'X73XFN', { accountName => 'anonymous-X73XFN@mailserver.com' } ]
    ]
  );

  # $result = { success => 1 }

Update postings from 3taps

Parameters

postings (arrayref)

An arrayref with one entry for each posting to be updated. Each posting's entry in the arrayref should itself be an arrayref with two entries: [postingKey, changes], where postingKey is the posting key identifying the posting to update, and changes is an hashref, containing key/value pairs mapping field names to their updated values.

Returns

An hashref with one boolean field called "success".

posting_delete

  my $api = WWW::3Taps::API->new;
  my $results = $api->posting_delete( postings => [ 'X73XFP', 'X73XFN' ] );

  # $result = { success => 1 }

Deletes postings from 3taps.

Parameters

postings (arrayref)

An arrayref of postKeys whose postKeys are to be deleted

Returns

An hashref with one boolean field called "success".

posting_exists

  my $api     = WWW::3Taps::API->new;
  my $results = $api->posting_exists(
    postings => [
      { source => 'E_BAY', externalID => '220721553191' },
      { source => 'CRAIG', externalID => '191' },
      { source => 'AMZON', externalID => '370468535518' }
    ]
  );

  # $results = [
  #   {
  #     exists => bless( do { \( my $o = 1 ) }, 'JSON::XS::Boolean' ),
  #     postKey => "5NUURN",
  #     time    => "2011-01-0800:38:22UTC"
  #   },
  #   {
  #     error  => "Heading cannot be null",
  #     exists => bless( do { \( my $o = 0 ) }, 'JSON::XS::Boolean' ),
  #     time   => "2011-01-08 00:38:22 UTC"
  #   },
  #   { exists => $VAR1->[1]{exists} }
  # ];

Returns information on the existence of postings. Note that this method is DEPRECATED and the Status API should be used instead.

Parameters

ids (arrayref)

An arrayref of hashrefs representing request objects with two fields: "source" and "externalID".

Returns

An arrayref of hashrefs representing a response objects with the following fields:

exists (boolean)

Returns true if this posting exists.

postKey (string)

The postKey of the post.

indexed (string)

The date that the posting was indexed by 3taps.

failures (arrayref)

An array of the failed attempts at saving this posting. Each failed attempt is represented as a hashref with the following fields:

postKey (string)

The postKey that was issued for this failed attempt

errors (arrayref)

An array of hashrefs representing the errors associated with this attempt

timestamp (date)

The time that this failure occurred.

posting_error

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

  # $results = {
  #   fields => [ 'source', 'category', 'location' ],
  #   post   => [ 'e_bay',  'SAPP',     'GBR' ],
  #   errors => ['externalID must be unique for this source']
  # };

Returns errors found when trying to process the given posting. Note that this method is DEPRECATED and the Status API should be used instead.

Parameters

postKey (string)

The postKey for the desired posting.

Returns

A hashref with some or all of the following fields:

fields (arrayref)

The fields submitted for this posting.

post (arrayref)

The values submitted for this posting.

errros (arrayref)

The errors found in the posting.

Geocoder API ^

The Geocoder API is a web service within the 3taps Network that allows other programs (both external systems and other parts of the 3taps Network) to calculate the location to use for a posting based on location-specific details within the posting such as a street address or a latitude and longitude value. This process of calculating the location for a posting is known as geocoding.

geocoder_geocode

  my $api     = WWW::3Taps::API->new;
  my $results = $api->geocoder_geocode(
    postings => [
      { text    => 'San Francisco, California' },
      { country => 'USA', state => 'CA', city => 'Los Angeles' }
    ]
  );

  # $results = [["SFO",37.77493,-122.41942],["LAX",34.05223,-118.24368]];

Calculate the location for a posting

Parameters

postings (arrayref)

An arrayref of hasrefs representing postings to geocode. Each entry in this array should contains one or more of the following fields:

latitude (float)

The GPS latitude value as a decimal degree.

longitude (float)

The GPS longitude value as a decimal degree.

country (string)

The GPS longitude value as a decimal degree.

state (string)

The name or code of the state or region.

city (string)

The name of the city.

locality (string)

The name of a suburb, area or town within the specified city.

street (string)

The full street address for this location.

postal (string)

A zip or postal code.

text (string)

An unstructured location or address value.

Returns

An arrayref with one entry for each posting. Each array entry will itself be an array with three entries:

  (locationCode, latitude, longitude)

where locationCode is the three-character location code to use for this posting, and latitude and longitude represent the calculated GPS coordinate for this posting’s location, in the form of floating-point numbers representing decimal degrees.

If the posting could not be geocoded at all, locationCode will be set to undef. If the geocoder was unable to calculate a lat/long value for the posting based on the supplied location details, latitude and longitude will be set to undef.

Notifications API ^

The 3taps Notifier constantly monitors all incoming postings, and sends out notifications via email, XMPP, Twitter, or iPhone Push as postings that match certain criteria are received. External users and systems are able to send a request to the Notification API to have notifications sent out to a given destination for all postings that meet a given set of criteria. These notifications will continue to be sent out until the request is explicitly cancelled or the request expires, usually after a period of seven days.

NOTE: Third party developers will need to contact us before they can use the Notifications API before they use it, so they can register their app with us. We're documenting this here to just let developers know what is available.

notifications_firehose

  my $api     = WWW::3Taps::API->new;
  my $results = $api->notifications_firehose(
    text     => 'honda',
    category => 'VAUT',
    location => 'LAX',
    name     => 'Hondas in LA'
  );

Creates an XMPP firehose. A variant of create. Supports the use of Common Search Criteria.

Parameters

name (string)

The name to give this firehose (optional)

Returns

A hashref with the following fields

success (boolean)

true/false depending on if the subscription was successfully created.

jid (string)

The XMPP jid of the newly created firehose.

username (string)

The username of the jid account of the newly created firehose.

password (string)

The password of the jid account of the newly created firehose.

id (string)

The id of the subscription associated with the firehose (to be used with delete)

secret (string)

The secret key to use when deleting this firehose (to be used with delete)

error (hashref)

If the firehose could not be created, error will be a hashref with two fields: "code", "and "message".

notifications_delete

  my $api     = WWW::3Taps::API->new;
  my $results = $api->notifications_delete(
    id     => '1873',
    secret => "201d7288b4c18a679e48b31c72c30ded"
  );

Cancel a notification subscription.

Parameters

id (string)

The id of the notification subscription to delete.

secret (string)

The secret key that was returned to you when you created the notification subscription. You kept it, right?

Returns

A hashref with the following fields:

success (boolean)

true/false depending on if the subscription was successfully deleted.

error (hashref)

If the delete was unsuccessful, error will contain a hashref with two fields: code, and message.

notifications_get

  my $api     = WWW::3Taps::API->new;
  my $results = $api->notifications_get(
    id     => '1873',
    secret => "201d7288b4c18a679e48b31c72c30ded"
  );

Get information about a notification subscription.

Parameters

id (string)

The id of the notification subscription to delete.

secret (string)

The secret key that was returned to you when you created the notification subscription. You kept it, right?

Returns

A hashref with the following fields:

subscription (hashref)

A hashref containing information about the notification subscription.

error (hashref)

If the delete was unsuccessful, error will contain a hashref with two fields: code, and message.

notifications/create

  my $api     = WWW::3Taps::API->new;
  my $results = $api->notifications_create(
    text        => 'red',
    location    => 'LAX',
    source      => 'CRAIG',
    annotations => { price => "200", make => "honda" },
    email       => 'dfoley@3taps.com',
    name        => 'red things in los angeles'
  );

Ask the notifier to start sending out notifications by creating a new "subscription".

Subscriptions need one delivery param (email, jid, token) and at least one Common Search Criteria parameter.

In order to eliminate unwanted strain on both the notification server and clients, the system will examine filter criteria before creating a subscription to make sure that the criteria is not too broad. If you try to subscribe to "all of eBay" you will get an error telling you to narrow your criteria.

Note that right now, only the following search params are available: loc, src, cat, text, price, annotations.

Parameters

name (string)

The name to give this subscription. This will be included in iPhone Push notifications. (optional).

expiration (integer)

The number of days to keep this subscription around for (default 7 days)

format (string)

Defines how the notifications should be formatted. The following formats are currently supported:

push

This format is intended for iPhone push notifications. The notification includes the following information in a single line: subscription name; the number of notifications received on this subscription today; the heading of the post.

brief

This format is intended for short, human-readable messages such as watching notifications on a chat client. The notification has two lines for the post: the heading, followed by a line break and the URL used to access the post within the 3taps system.

full
extended

These two formats are intended for sending notifications to external systems for further use. The data is sent as a JSON-encoded array with two entries: [fieldList, postings], where fieldList is an array of field names, and postings is an array of postings, where each posting is itself an array of field values, in the same order as the fieldList list.

For the full format, the following fields will be included:

  postKey
  source 
  category
  location
  heading
  body
  workspaceURL
  created

The extended format includes all the fields from the full format, plus:

  externalURL
  externalID
  trustedAnnotations
  latitude
  longitude
  price
  currency
  language
html

This format is intended for human-readable notifications such as emails. The following information is presented in HTML format:

  postKey
  source
  category
  location
  heading
  body
  workspaceURL
  created
text140

This format is intended to send notifications to Twitter; a minimal set of fields are included, and limited to 140 characters so that the notification can be sent out as a Twitter status update

email (string)

The email address to send this notification to.

jid (string)

The XMPP JID to send this notification to.

token (string)

The iPhone Device Token to send this notification to. (Note that you should only supply one of email, jid, or token.)

app (string)

The name of the app this notification subscription is being created from.

Returns

An arrayref with the following values:

success

true or false, depending on if the notification subscription was successfully created.

id

The id of the newly created subscription. This field is only returned on success.

secret

The secret pass for the newly created subscription, required for deleting subscriptions. This field is only returned on success.

error

If there was a problem with the API request, the error message will be included here as a hashref with two fields: code, and message. This field is only returned on failure.

AUTHORS ^

  Eden Cardim, C << <edencardim at gmail.com> >>
  Gabriel Andrade,  << <gabiruh 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.

syntax highlighting: