Search API

The Search API allows clients to query 3taps for data, and data about data. Most of the methods of the Search API accept a set of common parameters, we'll call the Common Search Criteria.
postKey STRING Postings must have this postKey to be found/processed.
externalID STRING Postings must have this externalID to be found/processed.
location STRING 3-character code reprepresenting the location that postings must be associated with to be found/processed. Multiple locations may be specified by passing in multiple location codes, separated by +OR+.
category STRING 4-character code reprepresenting the category that postings must be associated with to be found/processed. Multiple categories may be specified by passing in multiple category codes, separated by +OR+.
source STRING 5-character code reprepresenting the source that postings must be associated with to be found/processed. Multiple sources may be specified by passing in multiple source codes, separated by +OR+.
heading STRING Postings must have this string in their heading to be found/processed. Supports "quoted phrases", -not, and OR.
body STRING Postings must have this string in their body to be found/processed. Supports "quoted phrases", -not, and OR.
text STRING Postings must have this string in their body or heading to be found/processed. Supports "quoted phrases", -not, and OR.
accountID STRING Postings must have been created by this accountID to be found/processed.
price STRING Postings must have this price to be found/processed. The price field supports ranged values.
status STRING Postings must have this status to be found/processed.
start DATE Postings must have a timestamp value after start to be found/processed.
end DATE Postings must have a timestamp value before end to be found/processed.
indexedStart DATE Postings must have an indexed value after start to be found/processed.
indexedEnd DATE Postings must have an indexed value before end to be found/processed.
annotations OBJECT Postings must have these key/value pairs in annotations to be found/processed. The annotations field supports ranged values.
Many of the Common Search Criteria parameters refer to values in the Posting Object. There are times when you may need to query for a range of values. Some Common Search Criteria parameters support ranged values, meaning they allow you to query for a range of values. The format is as follows:
<200Postings must have a value of less than 200 to be found/processed.
>100Postings must have a value of greater than 100 to be found/processed.
100-200Postings must have a value between 100 and 200 to be found/processed.
Because of special characters in ranged values, range value-supporting parameters are always of type STRING, even though they are querying numeric values.

  1. search

    GET /search?[param]=[value]&[param2]=[value2]...

    Searches 3taps for postings. Supports the Common Search Criteria. A request to search with no Common Search Criteria params will return all postings.

    Params

    rpp INTEGER The number of results to return per page. Default is 100.
    page INTEGER The page number of results to return, where 0 is the first page of results. Default is 0.
    image STRING If set to "yes" search results will be limited to only contain postings with images. If set to "no" search results will be limited to only contain postings without images.
    retvals STRING A comma-separated list of the fields to return for each posting that matches the given search criteria. A list of available fields can be found in the posting object. Default retvals are category, location, heading, externalURL, and timestamp.
    sort STRING The field to sort by. By default, searches are sorted by timestamp, descending. Other options include price, relevancy, and indexed.
    reverse STRING If set to "true", the sort order will be reversed (ascending instead of descending).

    Returns

    Object The body of the response is a JSON encoded object with the following fields:
    successARRAYIf the search was a success, this will be true.
    numResultsINTEGERThe total number of results found for this search.
    execTimeMsINTEGERThe amount of time it took 3taps to perform your search, in milliseconds.
    errorSTRINGIf success is false, error will contain the error message
    resultsARRAYAn array of posting objects, each containing the fields specified in retvals

    Example URL

    http://api.3taps.com/search?source=E_BAY&location=LAX&authID=[your API key]

    Sample Code

    var params = {
	location: 'LAX+OR+NYC', 
	category: 'VAUT',
	annotations: '{make: "porsche", price:">1000"}'
};
threeTapsSearchClient.search(params, callback);
    back to top

  2. range

    GET /search/range?fields=[field],[field2]&[param]=[value]&[param2]=[value]

    Returns the minium and maximum values currently in 3taps for the given fields that match the given Common Search Criteria. The purpose of the range method is to provide developers with sensible values for range-based UI filters.

    Params

    fields STRING 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

    OBJECT A JSON encoded object with the min and max values for each field.

    Sample Code

    var params = {
	location: 'LAX', 
	category: 'VAUT',
	annotations: '{make:"porsche"}',
	fields = 'year,price'
};
threeTapsSearchClient.range(params, callback);
    back to top

  3. summary

    GET /search/summary?dimension=[dimension]&[param]=[value]&[param2]=[value]

    Returns the total number of postings found in 3taps, across the given dimension, that match the given Common Search Criteria 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. You may currently search across dimensions source, category, and location.

    Params

    dimension STRING The dimension to summarize across: source, category, location, or an annotation.
    codes STRING A comma separated list of values to summarize across. Default values are
    sourceAll sources.
    categoryAll groups.
    locationOur top 10 most active locations
    annotationnone

    Returns

    OBJECT An object with the following fields:
    totalsOBJECTAn object with one field for each code summarized in the given dimension, along with the total found (matching the given Common Search Criteria).
    execTimeMsINTEGERThe number of milliseconds it took 3taps to retrieve this information for you. Mainly used to let us know if we're slipping up.

    Sample Code

    var params = {
	text: 'toyota', 
	dimension: 'location'
};
threeTapsSearchClient.summary(params, callback);
    back to top

  4. count

    GET /search/count?[param]=[value]&[param2]=[value2]...

    Returns the total number of postings that match the given Common Search Criteria.

    Params

    There are no params for this method.

    Returns

    OBJECT An object with a single field, count, holding the number of matches found for the given parameters.

    Sample Code

    var params = {
	location: 'LAX', 
	category: 'VAUT',
	annotations: '{make:"porsche"}'
};
threeTapsSearchClient.count(params, callback);
    back to top