Search across multiple craigslist locations
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



A library to help search across multiple craigslist locations.


There are two ways to search craigslist using crags. You can search by keyword in a single location scoped to a category. You can also search by keyword across a country scoped by category. Each search type also has a set of configurable options.

Single Location Search


  default: bicycle (because bicycles are awesome)
  default: (because that is where it all began)
  default: for sale (because buying another bike is always a good idea)

Locations and Categories are full-on Ruby objects. You can get all of the Categories using:


Search a single craigslist location (e.g.

s = => 'shoes')
s.keyword     # shoes instead of bicycle
s.location    # the sfbay Location
s.category    # the 'for sale' Category
s.items       # a set of Items that match the search criteria

Each Item has a title, url (which is the link to the item on craigslist), and a date, which is the date the item was posted on craigslist.

Country Search


  default: bicycle (because bicycles are awesome)
  default: for sale (because buying another bike is always a good idea)
  default: us (because that is where I live)
  default: 1 (because hammering the cl servers will make em' angry)

Country searches are a combined set of individual location searches. Crags imposes a 1 second delay between each location search in order not to overload the Craigslist servers. You can change this at your own risk, but doing a lot of country wide searches with a 0s interval will probably get your IP banned.


gem install crags

Note on Patches/Pull Requests

  • Fork the project.

  • Make your feature addition or bug fix.

  • Add tests for it. This is important so I don't break it in a future version unintentionally.

  • Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)

  • Send me a pull request. Bonus points for topic branches.


Copyright © 2009 Justin Marney. See LICENSE for details.