Craigslist APIcraigslist.org ↗
Access Craigslist listings, regional sites, and category data via API. Search apartments, vehicles, jobs, and more across all Craigslist regions.
What is the Craigslist API?
The Craigslist API covers 4 endpoints that expose listings, regional site metadata, and category mappings across every Craigslist region worldwide. Use search_listings to query any category — apartments, vehicles, jobs, gigs, missed connections — with filters for price, images, and sort order, then retrieve full posting details including coordinates, images, and address via get_listing_detail.
No input parameters required.
curl -X GET 'https://api.parse.bot/scraper/e5511f29-7fc5-4bb6-aeed-3f14ac55789e/get_sites' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace craigslist-org-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Craigslist SDK — search listings, drill into details, browse sites."""
from parse_apis.craigslist_api import Craigslist, Category, Sort, ListingNotFound
craigslist = Craigslist()
# List regional sites to discover valid hostnames
for site in craigslist.sites.list(limit=3):
print(site.hostname, site.description, site.country)
for sub in site.sub_areas:
print(f" {sub.abbreviation}: {sub.description}")
# Search furniture listings in New York sorted by price
for listing in craigslist.listings.search(
site="newyork.craigslist.org",
query="couch",
category=Category.FURNITURE,
sort=Sort.PRICE_ASC,
min_price=100,
max_price=800,
limit=5,
):
print(listing.title, listing.price, listing.location)
# Drill into the first result for full details
listing = craigslist.listings.search(
site="sfbay.craigslist.org",
category=Category.ELECTRONICS,
limit=1,
).first()
if listing:
detail = listing.details()
print(detail.title, detail.price, detail.description[:100])
print(detail.latitude, detail.longitude, detail.posted_date)
# Handle a listing that no longer exists
try:
gone = craigslist.listings.search(
site="chicago.craigslist.org",
category=Category.BICYCLES,
limit=1,
).first()
if gone:
gone.details()
except ListingNotFound as exc:
print(f"Listing gone: {exc.url}")
print("exercised: sites.list / listings.search / listing.details / ListingNotFound")
Retrieve all Craigslist regional sites worldwide. Each site includes its hostname (used in search_listings), geographic coordinates, country, region, and available sub-areas. This is the reference endpoint for discovering valid site hostnames.
No input parameters required.
{
"type": "object",
"fields": {
"items": "array of site objects with AreaID, Hostname, Description, Region, Country, Latitude, Longitude, SubAreas"
},
"sample": {
"data": {
"items": [
{
"AreaID": 1,
"Region": "CA",
"Country": "US",
"Hostname": "sfbay",
"Latitude": 37.5,
"SubAreas": [
{
"SubAreaID": 1,
"Description": "city of san francisco",
"Abbreviation": "sfc",
"ShortDescription": "san francisco"
}
],
"Timezone": "America/Los_Angeles",
"Longitude": -122.25,
"Description": "SF bay area",
"Abbreviation": "sfo",
"ShortDescription": "SF bay area"
}
]
},
"status": "success"
}
}About the Craigslist API
Regional Sites and Categories
get_sites returns every Craigslist regional site as a structured object: AreaID, Hostname, Description, Region, Country, latitude/longitude, and an array of SubAreas (each with Abbreviation, Description, and SubAreaID). The Hostname value — for example newyork.craigslist.org — is the required input for search_listings. get_categories returns a flat dictionary mapping category codes to display names, covering dozens of categories from apa (apartments / housing for rent) to cta (cars+trucks) to mis (missed connections) and ggg (gigs).
Searching Listings
search_listings accepts a site hostname plus optional filters: query text, category code, sort order (relevant, date, priceasc, pricedsc), max_price, has_image, limit, and offset for pagination. Each result includes id, title, price (integer dollars; -1 for price-free categories), url, location, posted_date (ISO timestamp), images array, thumbnail, and housing-specific fields bedrooms and sqft where applicable.
Listing Detail
get_listing_detail takes a full listing URL that must include the subarea and category path segments — for example https://newyork.craigslist.org/mnh/mis/d/<slug>/<id>.html. It returns richer fields than the search results: city, region, address, latitude, longitude, a formatted price string with currency symbol, and a full images array. Expired or removed postings return a stale_input error rather than empty data, so callers should handle that response explicitly.
Coverage Notes
The API covers the full public listing surface: all categories returned by get_categories, all regional sites returned by get_sites, and both summary (search) and detail views of individual postings. Listings that require a Craigslist account to view are not accessible. The posted_date field may be null on some listings depending on how recently the data was indexed.
The Craigslist API is a managed, monitored endpoint for craigslist.org — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when craigslist.org changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official craigslist.org API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Monitor apartment listings in a specific city by polling
search_listingswith categoryapaandmax_priceto track rental market changes. - Build a vehicle price aggregator by searching category
ctaacross multiple regionalHostnamevalues and comparingpricefields. - Track job postings in a metro area by searching the
jjjcategory with a keywordqueryand sorting bydate. - Alert users to new gig listings by checking
search_listingswith categorygggand filtering byhas_imageand recency viaposted_date. - Enrich listing data for a real estate tool by calling
get_listing_detailto retrievelatitude,longitude,address, andbedroomsfor each result. - Populate a regional site selector UI using
get_sitesdata —Description,Country, andSubAreas— without maintaining a static list. - Cross-reference listing categories by mapping
get_categoriescodes to display names for a search interface or analytics pipeline.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Craigslist have an official developer API?+
What does `get_listing_detail` return beyond what `search_listings` includes?+
get_listing_detail returns fields not present in search results: address, city, region, latitude, and longitude. It also returns price as a formatted string with a currency symbol rather than a raw integer, and provides the full images array rather than just a thumbnail. The URL passed must include the subarea and category path segments or the request will fail.How does pagination work in `search_listings`?+
offset and limit parameters together. Set limit to control how many results come back per call, then increment offset by that amount on subsequent calls. There is no cursor or total-count field in the response, so callers should stop paginating when the returned result count falls below the requested limit.Does the API expose seller contact information or reply-to email addresses from listings?+
Are there any quirks with listing URLs returned by `search_listings`?+
url field in search results uses a simplified format that may omit subarea or category path segments. get_listing_detail requires a full URL with those segments present. If you plan to call get_listing_detail on search results, verify the URL structure matches the expected pattern before passing it — or construct the URL from the id and known site hostname.