Craigslist Search Driver

This module makes for simple retrieval of search results from Craigslist!

Installation

npm install node-craigslist

Usage

Methods optionally accept a callback argument - when supplied, the function will execute the callback with two arguments (err and results). When omitted, the method call will return a Promise.

Constructor

When constructing the craigslist client, options specified are used for all subsequent requests (i.e. #list and #search).

Usage: new craigslist.Client(options)

• options - (optional) - can be used to supply additional options - see Options for details
  • city - (optional) - defines the city for the search (NOTE: this field is required by #list and #search when not specified in the constructor)
  • baseHost - (optional) - allows for specification of the base domain (defaults to craiglist.org) to support other countries (i.e. for Canada, craigslist.ca)
  • maxPrice - (optional) - maximum price
  • minPrice - (optional) - minimum price
  • category - (optional) - allows for specification of the category (defaults to sss) to search in other categories
  • nocache - (optional) - applies appropriate headers on request to attampt to bypass any caches

const craigslist = require('node-craigslist');

let client = new craigslist.Client({
  baseHost : 'craigslist.ca',
  city : 'Toronto'
});

#list

This method can be used to grab a listing of Craigslist postings.

Usage: client.list(options, callback)

• options - (optional) - can be used to supply additional options - see Options for details
  • city - (optional) - defines the city for the search (NOTE: this field is required when city is not specified in the constructor)
  • baseHost - (optional) - allows for specification of the base domain (defaults to craiglist.org) to support other countries (i.e. for Canada, craigslist.ca)
  • maxPrice - (optional) - maximum price
  • minPrice - (optional) - minimum price
  • offset - (optional) - offset number of listings returned
  • category - (optional) - allows for specification of the category (defaults to sss) to search in other categories
  • nocache - (optional) - applies appropriate headers on request to attampt to bypass any caches
• callback - (optional) - a function callback that accepts two arguments - if omitted, the function will return a Promise
  • err - populated with details in the event of an error
  • result - result set details

To use it, it's as simple as the following example:

var
  craigslist = require('node-craigslist'),
  client = new craigslist.Client({
    city : 'seattle'
  });

client
  .list()
  .then((listings) => {
    // play with listings here...
    listings.forEach((listing) => console.log(listing));
  })
  .catch((err) => {
    console.error(err);
  });

Example response:

[
  {
    pid: '1234567890',
    category: 'video gaming - by owner',
    date: 'Mar  1',
    hasPic: true,
    price: '250',
    title: 'NEW & UNSEALED XBOX 360 - 250 GB BLACK FRIDAY BUNDLE',
    url: 'https://seattle.craigslist.org/see/vgm/4355583965.html'
  },
  /* results abbreviated */
]

#search

This method can be used to search Craigslist for specific postings.

Usage: client.search(options, query, callback)

• options - (optional) - can be used to supply additional options - see Options for details
  • baseHost - (optional) - allows for specification of the base domain (defaults to craiglist.org) to support other countries (i.e. for Canada, craigslist.ca)
  • bundleDuplicates - (optional) - when specified, duplicate listings are collapsed on search per Craigslist functionality
  • category - (optional) - allows for specification of the category (defaults to sss) to search in other categories
  • city - (optional) - defines the city for the search (NOTE: this field is required when city is not specified in the constructor)
  • hasPic - (optional) - when specified, only postings with images are returned
  • maxPrice - (optional) - maximum price
  • minPrice - (optional) - minimum price
  • offset - (optional) - offset number of listings returned
  • postal - (optional) - when specified in conjunction with searchDistance, the postal code can be used to find posting within a certain range
  • searchDistance - (optional) - when specified in conjunction with postal, this is the distance range
  • searchNearby - (optional) - allows for a search to be performed against nearby locations as well
  • searchTitlesOnly - (optional) - performs search against posting titles only and not the posting body
  • nocache - (optional) - applies appropriate headers on request to attampt to bypass any caches
  • minYear - (optional) - minimum year (cars+trucks related search)
  • maxYear - (optional) - maximum year (cars+trucks related search)
  • minMiles - (optional) - minimum miles (cars+trucks related search)
  • maxMiles - (optional) - maximum miles (cars+trucks related search)
  • autoMakeModel - (optional) - auto make model (cars+trucks related search)
  • minBedrooms - (optional) - minimum bedrooms (housing related search)
  • maxBedrooms - (optional) - maximum bedrooms (housing related search)
  • minBathrooms - (optional) - minimum bathrooms (housing related search)
  • maxBathrooms - (optional) - maximum bathrooms (housing related search)
  • minSqft - (optional) - minimum square ft (housing related search)
  • maxSqft - (optional) - maximum square ft (housing related search)
  • dogsOk - (optional) - when specified, only postings where dogs are ok (housing related search)
• query - (required) - a string query to search with
• callback - (optional) - a function callback that accepts two arguments - if omitted, the function will return a Promise
  • err - populated with details in the event of an error
  • result - result set details

To use it, it's as simple as the following example:

var
  craigslist = require('node-craigslist'),
  client = new craigslist.Client({
    city : 'seattle'
  });

client
  .search('xbox one')
  .then((listings) => {
    // play with listings here...
    listings.forEach((listing) => console.log(listing));
  })
  .catch((err) => {
    console.error(err);
  });

In order to search and filter by category and by price, check out the following example:

var
  craigslist = require('node-craigslist'),
  client = new craigslist.Client({
    city : 'seattle'
  }),
  options = {
    category : 'ppa',
    maxPrice : '200',
    minPrice : '100'
  };

client
  .search(options, 'xbox one')
  .then((listings) => {
    // filtered listings (by price)
    listings.forEach((listing) => console.log(listing));
  })
  .catch((err) => {
    console.error(err);
  });

Example response:

[
  {
    pid: '1234567890',
    category: 'video gaming - by owner',
    date: 'Mar  1',
    hasPic: true,
    price: '250',
    title: 'NEW & UNSEALED XBOX 360 - 250 GB BLACK FRIDAY BUNDLE',
    url: 'https://seattle.craigslist.org/see/vgm/4355583965.html'
  },
  /* results abbreviated */
]

#details

This method can be used to grab additional information for a specified listing.

Usage: client.details(listing, callback)

• listing - (required) - may be a listing object from a previous #search or #list call or a string URL to the specified posting
• callback - (optional) - a function callback that accepts two arguments - if omitted, the function will return a Promise
  • err - populated with details in the event of an error
  • result - result set details

To grab details for a listing, see the following example:

var
  craigslist = require('node-craigslist'),
  client = new craigslist.Client({
    city : 'seattle'
  });

client
  .list()
  .then((listings) => client.details(listings[0]))
  .then((details) => {
    console.log(details);
  })
  .catch((err) => {
    console.error(err);
  });

Example response (NOTE: not all fields are populated if additional information is not found, including phone, contact name, email, images, postedAt and updatedAt):

{
  "description": "My setup that taught me everything from mixing to scratching. A pair of DJ Consoles by DENON, a 2 channel mixer by Numark, all power supplies and RCA cables included, + ROAD CASE with wheels. I spent just over $1600 on this setup almost 5 years ago. Would love to see the whole thing go as a package, you can have it for $400. Come play around with it before you buy and see how awesome the scratching aspect is! Feels like real 7\'\' records!\n\nIncluded:\nPair of DENON DN-S3000\'s\nNumark DM1050 2 channel Mixer (+ Power Supply)\nRoad Read case with wheels\nRCA Cables for hook up\n\nHoller at me, email, call, or text.\nCheers,\nBro",
  "mapUrl": "https://maps.google.com/maps/preview/@47.690237,-122.344437,16z",
  "pid": "XXXXXXXXXX",
  "replyUrl": "http://seattle.craigslist.org/reply/sea/msg/XXXXXXXXXX",
  "title": "DJ Setup (DENONS + Mixer + Case)",
  "url": "https://seattle.craigslist.org/see/msg/XXXXXXXXXX.html",
  "postedAt": "2016-08-01T21:39:57.000Z",
  "updatedAt": "2016-08-11T16:44:29.000Z",
  "images":
   [ "http://images.craigslist.org/XX404_ggud0ZU38XX_600x450.jpg",
     "http://images.craigslist.org/XXP0P_h2cCxOdjCXX_600x450.jpg,"
     "http://images.craigslist.org/XXm0m_khEDbKM7fXX_600x450.jpg",
     "http://images.craigslist.org/XXZ0Z_c7xXA2eiCXX_600x450.jpg",
     "http://images.craigslist.org/XXp0p_1jB0EqCaqXX_600x450.jpg" ],
  "contactName": "Bro",
  "phoneNumber": "(XXX) XXX-XXXX",
  "email": "[email protected]"
}

Options

Per request, options can be modified to specify the following:

• a different city than whatever is specified during initialization (city option)
• a different country than whatever is specified during initialization (baseHost option)
• min and max price ranges (maxPrice and minPrice options)
• category (category option)

var
  craigslist = require('node-craigslist'),
  client = new craigslist.Client({
    city : 'seattle'
  }),
  options = {
    baseHost : '', // defaults to craigslist.org
    category : '', // defaults to sss (all)
    city : '',
    maxPrice : '200',
    minPrice : '100'
  };

client
  .search(options, 'xbox one')
  .then((listings) => {
    // listings (from Boston instead of Seattle)
    listings.forEach((listing) => console.log(listing));
  })
  .catch((err) => {
    console.error(err);
  });

Categories

This list may change based on Craigslist updates, but at the time of v1.9, this is the current list:

• sss = all
• ata = antiques
• ppa = appliances
• ara = arts+crafts
• sna = atvs/utvs/snow
• pta = auto parts
• baa = baby+kids
• bar = barter
• haa = beauty+hlth
• bip = bike parts
• bia = bikes
• bpa = boat parts
• boo = boats
• bka = books
• bfa = business
• cta = cars+trucks
• ema = cds/dvd/vhs
• moa = cell phones
• cla = clothes+acc
• cba = collectibles
• syp = computer parts
• sya = computers
• ela = electronics
• gra = farm+garden
• zip = free stuff
• fua = furniture
• gms = garage sales
• foa = general
• hva = heavy equipment
• hsa = household
• jwa = jewelry
• maa = materials
• mpa = motorcycle parts
• mca = motorcycles
• msa = music instr
• pha = photo+video
• rva = RVs
• sga = sporting
• tia = tickets
• tla = tools
• taa = toys+games
• vga = video gaming
• waa = wanted

Listing Object

Each listing returned has several properties... see the example below:

{ pid: '1234567890',
  category: 'video gaming - by owner',
  date: 'Mar  1',
  hasPic: true,
  price: '250',
  title: 'NEW & UNSEALED XBOX 360 - 250 GB BLACK FRIDAY BUNDLE',
  url: 'https://seattle.craigslist.org/see/vgm/4355583965.html' }