Node-craigslist NPM

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 &amp; 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 &amp; 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": "XXX-XXXX@XXXX.com"
}

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);
  });

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 &amp; UNSEALED XBOX 360 - 250 GB BLACK FRIDAY BUNDLE',
  url: 'https://seattle.craigslist.org/see/vgm/4355583965.html' }

craigslist search

@babel/runtime-corejs2 cheerio debug reqlib

craigslist-search bip-pod-craigslist

5 years ago

5 years ago

5 years ago

6 years ago