Posting API

The Posting API allows developers to store and retrieve postings in the 3taps system. Before diving into the methods of the Posting API, let's first define the structure of the posting object.
postKey STRING The unique identifier for the posting in the 3taps system.
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.
heading STRING A short (max 255 character) piece of text that summarizes the posting. Think of it as the "title" of the posting.
body STRING The content of the posting.
latitude FLOAT The latitude of the posting.
longitude FLOAT The longitude of the posting.
country STRING The country that the posting is located in.
state STRING The state that the posting is located in.
county STRING The county that the posting is located in.
region STRING The region that the posting is located in.
metro STRING The metro area that the posting is located in.
city STRING The city that the posting is located in.
locality STRING The locality that the posting is located in.
zip STRING The zip that the posting is located in.
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.
amount STRING The amount of the posting, if any. May 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 ARRAY An array of strings, each containing the URL of an image associated with the posting.
status STRING The status of the posting: offered, lost, found, stolen, or wanted.
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. REQUIRED
expiration DATE The time that the posting should expire in the 3taps system. 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.
annotations OBJECT A set of searchable key/value pairs associated with this posting.
clickCount INTEGER The number of times a posting has been clicked on in the 3taps system.
externalId STRING Use externaID. DEPRECATED
userID STRING Use accountId. DEPRECATED
image STRING Use images. DEPRECATED

  1. get

    GET /posting/get/[postKey]

    Returns information about a single posting.

    Params

    postKey STRING The posting key for the desired posting.

    Returns

    OBJECT A posting object with one or more fields outlined above in the posting model. If the posting is not found, an error object will be returned instead.

    Example URL

    http://api.3taps.com/posting/get/X7J67W?authID=[your API key]

    Example Response

    {
  "heading":"OHSEN Dual Time Chronograph Alarm Mens Sport Watch Blue",
  "body":"This is a mens blue sports watch.",
  "source":"E_BAY",
  "location":"HKG",
  "category":"SGJE",
  "latitude":22.2855,
  "longitude":114.158,
  "price":0.99,
  "currency":null,
  "images":["http://thumbs1.ebaystatic.com/pict/1505272809088080_1.jpg", "http://thumbs2.ebaystatic.com/pict/1232ed.jpg"],
  "externalUrl":"http://cgi.ebay.com/OHSEN-Dual-Time-Chronograph-Alarm-Mens-Sport-Watch-Blue-/150527280908?pt=UK_Jewelery_Watches_Watches_MensWatches_GL",
  "userID":"shopping.power2",
  "timestamp":"20101130232514",
  "annotations": {
		"tags":["#eBay","#forsale","#jewelry","#HKG"],
		"ship_to_locations":{"0":"Worldwide"}
		},
  "externalId":"150527280908",
  "postKey":"X7J67W",
  "id":496269986,
  "accountName":"shopping.power2",
  "clickCount":null,
  "accountId":null,
  "expiration":null
}

    Sample Code

    threeTapsPostingClient.get('X7J67W', callback);
    back to top

  2. create

    POST /posting/create

    Saves a new posting in 3taps.

    Params

    postings ARRAY An array of posting objects to be saved in 3taps, each with one or more fields outlined above in the posting model. Note that source, category, heading, and timestamp are all required values for sending in postings.

    Returns

    ARRAY An array with one entry for each posting that was supplied. Each array entry will be an object with the following fields:
    postKeySTRINGThe postKey generated for this posting.
    errorsARRAYIf there was an error saving the posting, the errors field will contain an array of error objects.
    warningsARRAYIf there was a warning saving the posting, the warnings field will contain an array of error objects.

    Example Response

    [{postKey:"X73XFN"}, {error:{code: 5, message: "Duplicate externalID for this source."}}]

    Sample Code

    var posting1 = {
	source: 'E_BAY',
	category: 'SGBI',
	location: 'LAX',
	heading: 'Test Post 1 in Bicycles For Sale Category',
	body: 'This is a test post. One.',
	price: 1.00,
	currency: 'USD',
	annotations: {
		color: 'red',
		brand: 'Specialized'
	},
	externalURL: 'http://www.ebay.com'
};
var posting2 = {
	source: 'E_BAY',
	category: 'SGBI',
	location: 'LAX',
	heading: 'Test Post 2 in Bicycles For Sale Category',
	body: 'This is a test post. Two.',
	price: 2.00,
	currency: 'USD',
	externalURL: 'http://www.ebay.com/3jua8'
};
var postings = [posting1, posting2];
threeTapsPostingClient.create(JSON.stringify(postings), callback);
    back to top

  3. update

    POST /posting/update

    Calculate the location for a posting

    Params

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

    Returns

    OBJECT An object with one boolean field called "success".

    Sample Code

    var posting1 = ['X73XFN', {accountName: "anonymous-X73XFN@mailserver.com"}];
var posting2 = ['X73XFP', {price: 20.00}];
var data = [posting1, posting2];
threeTapsPostingClient.update(data, callback);
    back to top

  4. delete

    POST /posting/delete

    Deletes postings from 3taps.

    Params

    data STRING an array of postKeys whose postings are to be deleted.

    Returns

    OBJECT An object with one boolean field called "success".

    Sample Code

    var data = ['X7J67W', 'X7JZDY'];
threeTapsPostingClient.delete(JSON.stringify(data), callback);
    back to top