Craigslist Gem
Unofficial Ruby interface for programmatically accessing Craigslist listings.
Usage
Instantiation
require 'craigslist'
# A direct call to a city or category method will return an instance of the
# internal persistable object
Craigslist.city(:seattle)
=> <Craigslist::Persistable @city=:seattle>
# Additional setter methods can be chained to the persistable
# Setting a category such as :bikes will set the category_path which is mapped
# internally
Craigslist.city(:seattle).category(:bikes)
=> <Craigslist::Persistable @city=:seattle, @category_path="bia">
# Internal search criteria may be more conveniently set using dynamic methods
# for city and category
Craigslist.seattle.bikes
=> <Craigslist::Persistable @city=:seattle, @category_path="bia">
# Any subsequent chained methods will override any previously set attributes
c = Craigslist.seattle.bikes.limit(20).max_ask(200)
=> <Craigslist::Persistable
@city=:seattle,
@category_path="bia",
@limit=20,
@max_ask=200>
c.sfbay.limit(10).max_ask(100)
=> <Craigslist::Persistable
@city=:sfbay,
@category_path="bia",
@limit=10,
@max_ask=100>
# The persistable may also be instantiated given a block of attributes and
# their respective arguments
Craigslist do
city :seattle
category :bikes
limit 10
query 'road bike'
search_type :T
has_image true
min_ask 100
max_ask 200
end
=> <Craigslist::Persistable
@city=:seattle,
@category_path="bia",
@limit=10,
@query="road bike",
@search_type=:T,
@has_image=true,
@min_ask=100,
@max_ask=200>
Helpers
require 'craigslist'
# Return true if the city is a valid subdomain
Craigslist.valid_city?(:seattle)
=> true
# Return an array of internally mapped categories
Craigslist.categories
=> [:bikes, :books, ...]
# Return true if the category is internally mapped to its category path
Craigslist.valid_category?(:bikes)
=> true
# If the desired category is not mapped within the gem, the category_path can
# be set manually
Craigslist.seattle.category_path('bia')
=> <Craigslist::Persistable @city=:seattle, category_path="bia">
Fetching results
require 'craigslist'
# In its simplest usage, posts can be output using a chained method syntax
Craigslist.seattle.bikes.fetch
=> [{}, ...n]
# Max results can be specified in an argument to #fetch. Results can span
# multiple pages
Craigslist.seattle.bikes.fetch(150)
=> [{}, ...150]
# Max results can also be specified by setting the limit either in the chained
# method syntax or the block syntax
c = Craigslist.seattle.bikes.limit(10)
# OR
c = Craigslist do
city :seattle
category :bikes
limit 10
end
c.fetch
=> [{}, ...10]
Installation
Add this line to your Gemfile:
gem 'craigslist'
Then execute:
$ bundle
Or install it yourself as:
$ gem install craiglist
Documentation
http://rdoc.info/gems/craigslist
Support
- Ruby 1.9.3
- Ruby 2.0.0
Notice
This software is not associated with Craigslist and is intended for research purposes only. Any use outside of this may be a violation of Craigslist terms of use.
License
Copyright (c) 2013 Greg Stallings. See LICENSE for details.