pycraigslist API library
Project description
A fast and expressive Craigslist API wrapper.
Disclaimer
I do not work or have an affiliation with Craigslist.
This library is intended for educational purposes. It is not advised to crawl and download data from Craigslist.
Installation
pip install pycraigslist
Jump Start
Let’s find posts with keyword “Mazda Miata” in the East Bay Area, California:
import pycraigslist
miatas = pycraigslist.forsale.cta(site="sfbay", area="eby", query="Mazda Miata")
for miata in miatas.search():
print(miata)
>>> {'country': 'US',
'region': 'CA',
'site': 'sfbay',
'area': 'scz',
'category': 'cto',
'id': '7298072504',
'repost_of': '',
'last_updated': '2021-03-27 17:12',
'title': '2005 Mazda MX-5 Miata',
'neighborhood': 'santa cruz',
'price': '$3,250',
'url': 'https://sfbay.craigslist.org/scz/cto/d/santa-cruz-2005-mazda-mx-miata/7298072504.html'}
# ...
Background
This library is intended to be expressive and easy to use.
pycraigslist classes
pycraigslist.community (craigslist.org > community)
pycraigslist.events (craigslist.org > event calendar)
pycraigslist.forsale (craigslist.org > for sale)
pycraigslist.gigs (craigslist.org > gigs)
pycraigslist.housing (craigslist.org > housing)
pycraigslist.jobs (craigslist.org > jobs)
pycraigslist.resumes (craigslist.org > resumes)
pycraigslist.services (craigslist.org > services)
We can search for posts in parent classes. Let’s find paid gigs in Portland, Oregon:
import pycraigslist
paid_gigs = pycraigslist.gigs(site="portland", is_paid=True)
for gig in paid_gigs.search():
print(gig)
>>> {'country': 'US',
'region': 'OR',
'site': 'portland',
'area': 'mlt',
'category': 'lbg',
'id': '7295392821',
'repost_of': '7292985211',
'last_updated': '2021-03-22 13:00',
'title': 'Packing and moving',
'neighborhood': 'SE Portland',
'price': '',
'url': 'https://portland.craigslist.org/mlt/lbg/d/portland-packing-and-moving/7295392821.html'}
# ...
pycraigslist subclasses
Most pycraigslist classes have subclasses to allow for categorical searches. For example:
pycraigslist.forsale.bia (craigslist.org > for sale > bikes)
pycraigslist.forsale.cta (craigslist.org > for sale > cars & trucks)
pycraigslist.housing.apa (craigslist.org > housing > apartments / housing for rent)
pycraigslist.housing.roo (craigslist.org > housing > apartments / rooms & shares)
Finding pycraigslist subclasses
To search for subclasses, use .get_categories(). The resulting keys are the subclass names.
import pycraigslist
print(pycraigslist.housing.get_categories())
>>> {'apa': 'apartments / housing for rent',
'swp': 'housing swap',
'off': 'office & commercial',
'prk': 'parking & storage',
'rea': 'real estate',
'reb': 'real estate - by dealer',
'reo': 'real estate - by owner',
'roo': 'rooms & shares',
'sub': 'sublets & temporary',
'vac': 'vacation rentals',
'hou': 'wanted: apts',
'rew': 'wanted: real estate',
'sha': 'wanted: room/share',
'sbw': 'wanted: sublet/temp'}
If we’re interested in searching for vacation rentals, we’d use the subclass pycraigslist.housing.vac.
Finding and using filters
As demonstrated in the jump-start example, we can apply filters to our Craigslist search. To find valid filters for a class or subclass, use .get_filters().
import pycraigslist
print(pycraigslist.housing.apa.get_filters())
>>> {'query': '...', 'search_titles': 'True/False', 'has_image': 'True/False',
'posted_today': 'True/False', 'bundle_duplicates': 'True/False', 'search_distance': '...',
'zip_code': '...', 'min_price': '...', 'max_price': '...',
'min_bedrooms': '...', 'max_bedrooms': '...', 'min_bathrooms': '...',
'max_bathrooms': '...', 'min_ft2': '...', 'max_ft2': '...',
'private_room': 'True/False', 'private_bath': 'True/False', 'cats_ok': 'True/False',
'dogs_ok': 'True/False', 'is_furnished': 'True/False', 'no_smoking': 'True/False',
'wheelchair_acccess': 'True/False', 'ev_charging': 'True/False', 'no_application_fee': 'True/False',
'no_broker_fee': 'True/False',
'housing_type': ['apartment', 'condo', 'cottage/cabin', 'duplex', 'flat',
'house', 'in-law', 'loft', 'townhouse', 'manufactured',
'assisted living', 'land'],
'laundry': ['w/d in unit', 'w/d hookups', 'laundry in bldg', 'laundry on site', 'no laundry on site'],
'parking': ['carport', 'attached garage', 'detached garage', 'off-street parking', 'street parking',
'valet parking', 'no parking']}
Using this information, let’s search for apartments / housing for rent in Eugene, Oregon that have at least 1 bedroom and a carport:
import pycraigslist
one_bedrooms = pycraigslist.housing.apa(site="eugene", min_bedrooms=1, parking="carport")
for room in one_bedrooms.search():
print(room)
>>> {'country': 'US',
'region': 'OR',
'site': 'eugene',
'area': '',
'category': 'apa',
'id': '7267556874',
'repost_of': '',
'last_updated': '2021-02-24 08:55',
'title': 'High End, Spacious Top Floor Two Bedroom!',
'neighborhood': 'Eugene',
'price': '$1,550',
'url': 'https://eugene.craigslist.org/apa/d/springfield-high-end-spacious-top-floor/7267556874.html',
'bedrooms': '2',
'area-ft2': '1000'}
# ...
If we want to apply a bunch of filters, pass a dictionary of filters into the filters keyword parameter. Note: keyword argument filters will override filters if there are conflicting keys. For example:
import pycraigslist
bike_filters = {
"bicycle_frame_material": "steel",
# array of filter values are accepted
"bicycle_wheel_size": ["650C", "700C"],
"bicycle_type": "road",
}
# we'd still get titanium road bikes with size 650C or 700C wheels
titanium_bikes = pycraigslist.forsale.bia(
site="sfbay", area="sfc", bicycle_frame_material="titanium", filters=bike_filters
)
Searching for posts
General search
To search for Craigslist posts, use .search(). .search() will return a dictionary of attributes (type str) for every post and will get every post by default. Use the limit keyword parameter to add a stop limit to a query. For example, use limit=50 if we want 50 posts. There is a maximum of 3000 posts per query.
Let’s find the first 20 posts for farming and gardening services in Denver, Colorado:
import pycraigslist
gardening_services = pycraigslist.services.fgs(site="denver")
for service in gardening_services.search(limit=20):
print(service)
>>> {'country': 'US',
'region': 'CO',
'site': 'denver',
'area': '',
'category': 'fgs',
'id': '7301324564',
'repost_of': '6974119634',
'last_updated': '2021-04-03 11:47',
'title': '🌲 Tree Removal/Trimming, Stump Grind: LICENSED/INSURED! 720-605-1584',
'neighborhood': 'All Areas',
'price': '',
'url': 'https://denver.craigslist.org/fgs/d/littleton-tree-removal-trimming-stump/7301324564.html'}
# ...
Detailed search
Use .search_detail() to get detailed Craigslist posts. The limit keyword parameter in .search also applies to .search_detail. Set include_body=True to include the post’s body in the output. By default, include_body=False. Disclaimer: .search_detail is more time consuming than .search.
Let’s get detailed posts with the post body for all cars & trucks for sale in Abilene, Texas:
import pycraigslist
all_autos = pycraigslist.forsale.cta(site="abilene")
for auto in all_autos.search_detail(include_body=True):
print(auto)
>>> {'country': 'US',
'region': 'TX',
'site': 'abilene',
'area': '',
'category': 'cto',
'id': '7301439387',
'repost_of': '',
'last_updated': '2021-04-03 16:15',
'title': 'Ford F-250 Super Duty XLT',
'neighborhood': 'Abilene',
'price': '$16,000',
'url': 'https://abilene.craigslist.org/cto/d/abilene-ford-250-super-duty-xlt/7301439387.html',
'lat': '32.255519',
'lon': '-99.787999',
'address': '1226 County Road 150',
'misc': ['2005 chevrolet malibu', 'delivery available'],
'condition': 'good',
'cylinders': '6 cylinders',
'drive': 'fwd',
'fuel': 'gas',
'odometer': '140000',
'paint color': 'white',
'size': 'full-size',
'title status': 'clean',
'transmission': 'automatic',
'type': 'sedan',
'body': '05 Chev. Malibu. Run out good, stingy on gas.\nReady to go.'}
# ...
Additional attributes
__doc__: Gets category name.
url: Gets full URL.
count: Gets number of posts.
import pycraigslist
east_bay_apa = pycraigslist.housing.apa(site="sfbay", area="eby", max_price=800)
# 1
print(east_bay_apa.__doc__)
>>> 'apartments / housing for rent'
# 2
print(east_bay_apa.url)
>>> 'https://sfbay.craigslist.org/search/eby/apa?searchNearby=1&s=0&max_price=800'
# 3
print(east_bay_apa.count)
>>> 56
Contribute
Support
If you are having issues or would like to propose a new feature, please use the issues tracker.
License
The project is licensed under the MIT license.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for pycraigslist-0.4.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 1c9c0328fd7c2e84deb600e19158d4bdf1278e66b111eff3997f60745c39a68f |
|
MD5 | a1be0ab7a8552b6176004cda5357ae3f |
|
BLAKE2b-256 | 77a0739beb3aca8b4d3a4ac02c0429329a208d00c6e4c71926b50d168c782f33 |