Reference API

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

  1. location

    GET /reference/location

    Returns the 3taps locations. Note that you can request a single location by passing in the location code: http://api.3taps.com/reference/location/NYC

    Params

    There are no params for this method.

    Returns

    ARRAY an array of location objects. Location object fields:
    codeSTRINGA unique 3-character code identifying this location within 3taps.
    countryRankINTEGERA 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).
    countrySTRINGThe name of the country this location is in.
    cityRankINTEGERA 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).
    citySTRINGThe name of the city this location is in.
    stateCodeSTRINGA brief (usually two-letter) code for the state or region this location is in.
    stateNameSTRINGThe name of the state or region this location is in. This will be blank for countries which do not have states or regions.
    hiddenBOOLEANIf true, this location should be hidden from the user-interface.
    latitudeFLOATThe latitude of this location.
    longitudeFLOATThe longitude of this location.

    Example URL

    http://api.3taps.com/reference/location?authID=[your API key]

    Example Response

    [
		{
			"countryRank":1,
			"country":"United States",
			"cityRank":1,
			"city":"New York",
			"stateCode":"NY",
			"stateName":"New York",
			"code":"NYC",
			"latitude":40.6344,
			"longitude":-74.2827
		}
	]

    Sample Code

    threeTapsReferenceClient.location(callback);
    back to top

  2. category

    GET /reference/category

    Returns the 3taps categories. Note that you can request a single category by passing in the category code: http://api.3taps.com/reference/category/VAUT

    Params

    annotations BOOLEAN If set to set to false if you'd prefer to get the category data without annotations. (optional)

    Returns

    ARRAY An array of category objects. Category object fields:
    codeSTRINGA unique 4-character code identifying this category within 3taps.
    groupSTRINGThe name of the group of this category.
    categorySTRINGThe name of the category.
    hiddenBOOLEANIf true, this category should be hidden from the user-interface.
    annotationsARRAYAn array of annotation objects. Each annotation object may have the following fields:
    nameSTRINGThe name of this annotation.
    typeSTRINGThe type of the annotation. Possible types currently include "string", "select" and "number".
    optionsARRAYSuggested values for the annotation. Each suggestion is an OBJECT that can contain two fields: value and subannotation. Value will contain the string value of this option, while subannotation will contain an annotation object that can be applied to a posting or search if this option is selected.

    Example URL

    http://api.3taps.com/reference/category?authID=[your API key]

    Example Response

    [
		{
			"group":"For Sale",
			"category":"Art & Crafts",
			"code":"SANC",
			"annotations":[
				{
					"name":"Privacy Status",
					"type":"string",
					"options":[
						{"value":"anonymous"},
						{"value":"semi-anonymous"},
						{"value":"public"}
					]
				},
				{
					"name":"Registry Status",
					"type":"string",
					"options":[
						{"value":"own"},
						{"value":"sell"},
						{"value":"for free"},
						{"value":"share"},
						{"value":"auction"},
						{"value":"want \/ seek"},
						{"value":"deal"},
						{"value":"provide"},
						{"value":"lost"},
						{"value":"stolen"},
						{"value":"found \/ recovered"},
						{"value":"lease \/ sub-lease"},
						{"value":"leased"},
						{"value":"sold \/gone \/ expired"}
					]
				},
				{
					"name":"Price",
					"type":"string"
				},
				{
					"name":"UID",
					"type":"string"
				}
			]
		}
	]

    Sample Code

    threeTapsReferenceClient.category(callback);
    back to top

  3. source

    GET /reference/source

    Returns the 3taps sources. Note that you can request a single source by passing in the source code: http://api.3taps.com/reference/source/E_BAY

    Params

    There are no params for this method.

    Returns

    ARRAY An array of source objects Source object fields:
    codeSTRINGA unique 5-character code identifying this source within 3taps.
    nameSTRINGThe name of the source.
    logo_urlSTRINGThe URL of the logo to use for this source in the UI.
    logo_sm_urlSTRINGThe URL of a smaller, square logo to use for this source in the UI.

    Example URL

    http://api.3taps.com/reference/source?authID=[your API key]

    Example Response

    [
			{
				"name":"3taps",
				"code":"3TAPS",
				"logo_url":"http:\/\/3taps.com\/img\/logos\/3TAPS3taps.png",
				"logo_sm_url":"http:\/\/3taps.com\/img\/logos\/3TAPS3taps-fav.png"
			},
			{
				"name":"9-1-1alert",
				"code":"9-1-1",
				"logo_url":"http:\/\/3taps.com\/img\/logos\/9-1-19-1-1.png",
				"logo_sm_url":"http:\/\/3taps.com\/img\/logos\/9-1-19-1-1fav.png",
				"hidden":true
			},
			{
				"name":"Amazon",
				"code":"AMZON",
				"logo_url":"http:\/\/3taps.com\/img\/logos\/AMZONamazon.png",
				"logo_sm_url":"http:\/\/3taps.com\/img\/logos\/AMZONamazon-fav.png"
			},
			{
				"name":"craigslist",
				"code":"CRAIG",
				"logo_url":"http:\/\/3taps.com\/img\/logos\/CRAIGcraigslists.png",
				"logo_sm_url":"http:\/\/3taps.com\/img\/logos\/craig_ico.png"
			} 
		]

    Sample Code

    threeTapsReferenceClient.source(callback)
    back to top

  4. modified

    GET /reference/modified/[reference-type]

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

    Params

    reference-type STRING Can be "source", "category", or "location".

    Returns

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

    Example URL

    http://api.3taps.com/reference/modified/source?authID=[your API key]

    Example Response

    2010-12-08 22:29:38 UTC

    Sample Code

    threeTapsReferenceClient.modified(callback);
    back to top