Glossary
Before diving into the APIs, let's get familiar with the basic concepts of the 3taps universe.
API Key
Every application that uses the 3taps API must be registered before any calls can be issued. Once registered, your app will be assigned an API Key that identifies your app. You must include your API Key in every API call made, using the parameter name authID.
Posting
A posting is a piece of data that represents the availability or need for an exchange of goods or services. Examples of postings are: an auction on eBay.com, a tweet on Twitter, a job listing on Monster.com, a classified on Craigslist.org.
Each posting in 3taps has many attributes that help identify and describe it. The most important of these are:
Post Key
When 3taps ingests a posting into the system, it issues that posting a unique identifier called a post key.
External ID
Just as the 3taps post key uniquely identifies a posting in 3taps, the external ID uniquely identifies a posting in its source. For more information on sources, see below.
Annotations
Annotations are a list of searchable key/value pairs that can be applied to a posting. Examples of annotations include "make: Honda" and "bedrooms: 2".
"Trusted" Annotations
While 3taps allows developers to apply any annotations they like to a posting, we also maintain a list of annotations that we feel are "standard," and thus are supported. We call these "trusted annotations." Trusted annotations are associated with categories (see below).
Source
Each posting has a source. A source is the place that the posting data originated in. For example, the source of an eBay auction is "eBay". Each source in 3taps is given a unique 5-character code to identify it. The source for eBay is E_BAY. You can get the full list of sources from the Reference API.
Category
Every posting has a category. A category is a tag that identifies the type of the posting. Example categories are "Accounting Jobs" or "Antiques for Sale". While external categories may vary across sources, within 3taps, categories are normalized, allowing users to search by category across multiple sources. The list of available categories can be found in the Reference API.
Each category in 3taps is given a unique 4-character code to identify it. In addition to the usual fields such as code, and name, categories also have a few special fields:
Group
Similar categories may belong to groups. Like categories, groups are also identified with a 4-character code. Groups treated as special categories, and are returned as categories by the reference API.
Annotations
As discussed above, annotations are searchable key/value pairs associated with postings. Each category has one or more associated suggested annotations. For example, for the Vehicles category, 3taps recommends annotations like make and model. These suggested annotations are called "trusted annotations".
Location
Every posting also has a location. A location is a tag that identifies the location of a posting. Example locations are "Los Angeles", or "Illinois." Like categories, locations are normalized across sources, and the full list of locations can be retrieved from the Reference API.
Error
3taps error messages have two fields: message and code. A comprehensive list of errors can be found here.
Date
The 3taps API passes dates as strings using the following format: "YYYY/MM/DD hh:mm:ss UTC". It should be noted that dates sent into 3taps should be in UTC. The 3taps API will ignore the timezone field for inbound requests.
