This is an API client for the 3taps polling, reference and search API endpoints.
npm install 3taps
In the event that the 3taps API returns an unsupported HTTP status code (i.e. less than 200 or greater than 299) or when the success field from the return message is false, the callback will contain an error with the following properties:
{
requestOptions: {
method: 'GET',
qs: { auth_token: 'test-api-key', timestamp: 1417789575187 },
url: 'https://polling.3taps.com/anchor'
},
response: {
success: false,
error: 'example error',
request: {
body: '',
uri: '/anchor?auth_token=test-api-key×tamp=1417789575187'
}
},
statusCode: 409
}
Options are optional for every method call... the underlying 3taps API may return an error in the event that an expected parameter is missing, however. All parameters can be specified globally when initializing the client library and each initialized parameter value can be overridden in each module method call.
The following options are required when creating the client library:
apikey : the API key for access to the 3taps APIThe following options are optional when creating the client library:
maxRetryCount : defaults to 0 - the number of retries in the event that any error is returned when calling the APIpollingUrl : defaults to https://polling.3taps.comreferenceUrl : defaults to https://reference.3taps.comsearchUrl : defaults to https://search.3taps.comstrictSSL : defaults to truetimeout : defaults to 10000 (10 seconds)The polling endpoint supports two specific capabilities: anchor and poll
Use this to generate an anchor from a point in time... the timestamp value is supported as a Date value or the number of seconds from Unix epoch (January 1, 1970).
var
anchorDate = new Date(),
threeTapsClient = require('3taps')({ apikey : 'my-api-key' });
// retrieve all postings new in the last hour
anchorDate.setHours(anchorDate.getHours() - 1);
threeTapsClient.anchor({
timestamp : anchorDate
}, function (err, data) {
// work with data here
});
For which the response will look similar to the following:
{
success: true,
anchor: 1570197959
}
var threeTapsClient = require('3taps')({ apikey : 'my-api-key' });
threeTapsClient.poll({
anchor : 1570197959
}, function (err, data) {
// work with data here
});
The library will respond with something similar to:
{
success: true,
anchor: 124981255,
postings: [
{ id: 1570150577,
source: 'CRAIG',
category: 'RHFS',
external_id: '4757959490',
external_url: 'http://greensboro.craigslist.org/reb/4757959490.html',
heading: '6312 Settlement Road',
timestamp: 1417712270,
annotations: [Object],
deleted: false,
location: [Object] },
{ id: 1570150578,
source: 'CRAIG',
category: 'JMFT',
external_id: '4759338172',
external_url: 'http://fredericksburg.craigslist.org/mnu/4759338172.html',
heading: 'QA Technician',
timestamp: 1417711983,
annotations: [Object],
deleted: false,
location: [Object] },
// and so on...
]
}
Polling supports a series of parameters that can be passed in the options argument. For a full reference, please see the 3taps documentaiton at http://docs.3taps.com/polling_api.html. Additionally, many of the params support the ability to pass in the logical operators | (or) and - (not).
Here is an example list of options:
var options = {
anchor : 12345, // optional
category : '', // optional - 3taps category code, supports logical operators
'category_group' : '', // optional - 3taps category_group code, supports logical operators
'location' : {
'city' : '', // optional - desired City, supports logical operators
'country' : '', // optional - desired Country code, supports logical operators
'county' : '', // optional - desired County code, supports logical operators
'locality' : '', // optional - 3taps Locality code, supports logical operators
'metro' : '', // optional - 3taps Metro Area code, supports logical operators
'region' : '', // optional - 3taps Region code, supports logical operators
'state' : '', // optional - 3taps City code, supports logical operators
'zipcode' : '' // optional - desired Zip Code, supports logical operators
},
retvals : [''], // optional - list of fields to return (see below)
source : '', // optional - 3taps Data Source code, supports logical operators
state : '', // optional - state of the posting (see below), supports logical operators
status : '' // optional - status of the posting (see below), supports logical operators
};
threeTapsClient.poll(options, function (err, data) {
// filtered awesomeness in the data arg
});
The retvals parameter supports an array or a comma separated list of values from the following:
The state parameter supports the following values:
The status parameter supports the following values:
The reference API endpoint in 3taps returns information about categories, category_groups, sources and locations in addition to providing the ability to lookup a specific location to retrieve detailed information.
Important Note:
Periodically, the values from reference API methods will change... they can be cached, but periodically, the lastModified date should be used to determine if a value has been updated. The responses from #getCategories, #getCategoryGroups, #getDataSources and #getLocations will contain a lastModified field that can be used for this purpose.
var threeTapsClient = require('3taps')({ apikey : 'my-api-key' });
threeTapsClient.getCategories(function (err, data) {
// work with categories here
});
The response will look similar to the following:
{
categories: [{
code: 'APET',
group_code: 'AAAA',
group_name: 'Animals',
name: 'Pets'
}, {
code: 'ASUP',
group_code: 'AAAA',
group_name: 'Animals',
name: 'Supplies'
}, {
// ... more categories, etc.
}],
success: true,
lastModified: 'Tue Sep 10 2013 00:34:25 GMT-0700 (PDT)'
}
var threeTapsClient = require('3taps')({ apikey : 'my-api-key' });
threeTapsClient.getCategoryGroups(function (err, data) {
// work with category groups here
});
The response will look similar to:
{ category_groups:
[ { code: 'AAAA', name: 'Animals' },
{ code: 'CCCC', name: 'Community' },
{ code: 'DISP', name: 'Dispatch' },
{ code: 'SSSS', name: 'For Sale' },
{ code: 'JJJJ', name: 'Jobs' },
{ code: 'MMMM', name: 'Mature' },
{ code: 'PPPP', name: 'Personals' },
{ code: 'RRRR', name: 'Real Estate' },
{ code: 'SVCS', name: 'Services' },
{ code: 'ZZZZ', name: 'Uncategorized' },
{ code: 'VVVV', name: 'Vehicles' } ],
success: true,
lastModified: 'Mon Sep 02 2013 00:34:25 GMT-0700 (PDT)'
}
var threeTapsClient = require('3taps')({ apikey : 'my-api-key' });
threeTapsClient.getDataSources(function (err, data) {
// work with data sources here
});
The response will look similar to:
{ sources:
[ { code: 'APTSD', name: 'Apartments.com' },
{ code: 'AUTOC', name: 'autotraderclassic.com' },
{ code: 'AUTOD', name: 'autotrader.com' },
{ code: 'BKPGE', name: 'Backpage' },
{ code: 'CARSD', name: 'Cars.com' },
{ code: 'CCARS', name: 'classiccars.com' },
{ code: 'CRAIG', name: 'Craigslist' },
{ code: 'E_BAY', name: 'ebay.com' },
{ code: 'EBAYM', name: 'Ebay Motors' },
{ code: 'HMNGS', name: 'Hemmings Motor News' },
{ code: 'INDEE', name: 'Indeed' },
{ code: 'RENTD', name: 'Rent.com' } ],
success: true,
lastModified: 'Tue Sep 30 2014 00:34:25 GMT-0700 (PDT)'
}
This method requires the parameter level which should contain one of the following string values:
Additionally, the results returned can be filtered at the server by passing any of the following parameters:
See the following example to pull zipcodes within San Francisco:
var
options = {
level : 'zipcode',
city : 'USA-SFO-SNF'
},
threeTapsClient = require('3taps')({ apikey : 'my-api-key' });
threeTapsClient.getLocations(
options,
function (err, data) {
// work with locations here
});
Which returns data similar to the following:
{
locations: [{
bounds_max_lat: 37.78933,
bounds_max_long: -122.40438,
bounds_min_lat: 37.76963,
bounds_min_long: -122.42968,
code: 'USA-94102',
full_name: '94102',
short_name: '94102'
}, {
bounds_max_lat: 37.78823,
bounds_max_long: -122.39768,
bounds_min_lat: 37.76453,
bounds_min_long: -122.42615,
code: 'USA-94103',
full_name: '94103',
short_name: '94103'
}, {
// more results here...
}],
success: true,
lastModified: 'Mon Sep 02 2013 00:34:25 GMT-0700 (PDT)'
}
Provides the ability to find the details of a single location based on its code...
var
options = {
code : 'USA-94102'
},
threeTapsClient = require('3taps')({ apikey : 'my-api-key' });
threeTapsClient.lookupLocation(
options,
function (err, data) {
// work with location here
});
Which will return data similar to the following:
{ location:
{ bounds_max_lat: 37.78933,
bounds_max_long: -122.40438,
bounds_min_lat: 37.76963,
bounds_min_long: -122.42968,
code: 'USA-94102',
full_name: '94102',
level: 'zipcode',
short_name: '94102' },
success: true }
Search supports a series of parameters that can be passed in the options argument. For a full reference, please see the 3taps documentaiton at http://docs.3taps.com/search_api.html. Additionally, many of the params support the ability to pass in the logical operators | (or) and - (not).
Here is a list of all optional options:
timestamp, -timestamp, price, -price and distanceThe following example performs a search for all postings with fixie in the body located within San Francisco, California:
var
options = {
body : 'fixie',
'location.city' : 'USA-SFO-SNF'
},
threeTapsClient = require('3taps')({ apikey : 'my-api-key' });
threeTapsClient.search(
options,
function (err, data) {
// work with location here
});
The response is similar to the following:
{
"next_page": 1,
"time_search": 4.912137985229492,
"success": true,
"time_taken": 163.88916969299316,
"anchor": 1574246415,
"time_fetch": 5.389928817749023,
"num_matches": 33,
"postings": [
{
"category": "SBIK",
"timestamp": 1417790322,
"id": 1573798080,
"source": "CRAIG",
"location": {
"city": "USA-SFO-SNF",
"geolocation_status": 3,
"metro": "USA-SFO",
"locality": "USA-SFO-BEN",
"country": "USA",
"region": "USA-SFO-SAF",
"zipcode": "USA-94110",
"long": "-122.4158",
"county": "USA-CA-SAF",
"state": "USA-CA",
"lat": "37.74299",
"formatted_address": "Bernal Heights Summit, San Francisco, CA 94110, USA",
"accuracy": 8
},
"external_id": "4787190734",
"heading": "2013 Ridley Excalibur Road Bike Frame PRICE DROP Or Best Offer",
"external_url": "http://sfbay.craigslist.org/sby/bik/4787190734.html"
},
{
"category": "VPAR",
"timestamp": 1417790193,
"id": 1573694799,
"source": "CRAIG",
"location": {
"city": "USA-SFO-SNF",
"geolocation_status": 3,
"metro": "USA-SFO",
"locality": "USA-SFO-BEN",
"country": "USA",
"region": "USA-SFO-SAF",
"zipcode": "USA-94110",
"long": "-122.4158",
"county": "USA-CA-SAF",
"state": "USA-CA",
"lat": "37.74299",
"formatted_address": "Bernal Heights Summit, San Francisco, CA 94110, USA",
"accuracy": 8
},
"external_id": "4788044842",
"heading": "3T IONIC 25 TEAM STEALTH CARBON SEATPOST",
"external_url": "http://sfbay.craigslist.org/sby/bop/4788044842.html"
},
// more results ...
],
"next_tier": 0
}
The package.json file is wired up to run jshint, unit tests and code coverage reporting, but not functional tests when running npm test.
npm test
gulp jshint
gulp test-unit
When running test coverage, an istanbul report will be created at ./reports/lcov-report/lib/index.js.html
gulp test-coverage
open reports/lcov-report/lib/index.js.html
To run functional tests, you'll need to export an environment variable with your 3taps API key:
export THREETAPS_APIKEY=my-key-goes-here
To verify whether your key is properly set, simply echo from the command line:
echo $THREETAPS_APIKEY
note: You may want to consider adding this to your ~/.bash_profile so that it is always set when you open a terminal
Now, you can run the functional tests using gulp with the following command:
gulp test-functional
FAQs
Node client for 3taps API
We found that 3taps demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.
Research
Security News
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
Security News
NVD’s backlog surpasses 20,000 CVEs as analysis slows and NIST announces new system updates to address ongoing delays.