❤
npm
Sign UpSign In

node-craigslist

2.3.1 • Public • Published

Craigslist Search Driver

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

Build Status Coverage Status

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

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' }

Readme

Keywords

Package Sidebar

Install

npm i node-craigslist

Weekly Downloads

9

Version

2.3.1

License

MIT

Unpacked Size

85.7 kB

Total Files

11

Last publish

Collaborators

  • brozeph
Try on RunKit
Report malware