Divar APIdivar.ir ↗
Search Divar.ir classified ads by city, category, and keyword. Retrieve full listing details including price, location, images, and properties via two endpoints.
What is the Divar API?
The Divar.ir API provides access to Iran's largest classifieds marketplace through 2 endpoints. Use search_posts to query listings across 8 major Iranian cities filtered by category and free-text query, then call get_post_details with the returned token to retrieve a full listing record including price, description, geo-coordinates, item properties, and image URLs.
curl -X POST 'https://api.parse.bot/scraper/e66fc77c-35ea-444e-9f3a-be2eb642d380/search_posts' \
-H 'X-API-Key: $PARSE_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"city": "tehran",
"limit": "10",
"query": "موبایل",
"category": "ROOT"
}'Search and list classified ad posts on Divar. Accepts a city slug, optional free-text query, and category filter. Returns a list of post summaries including title, price text, location, and image info. Results are sorted by newest first. Each post carries a token usable with get_post_details for the full listing.
| Param | Type | Description |
|---|---|---|
| city | string | City slug for filtering posts. Accepted values: tehran, mashhad, karaj, shiraz, isfahan, ahvaz, tabriz, kermanshah, qom, rasht. Alternatively, pass a numeric city ID directly. |
| limit | integer | Maximum number of posts to return from the search results. |
| query | string | Free-text search query to match against post titles and descriptions. Empty string returns all recent posts. |
| category | string | Category slug to filter results. Use ROOT for all categories. Examples of category slugs: personal, clothing-and-shoes, clothing, vehicles, real-estate, digital-goods, home-kitchen, services, entertainment, industrial, jobs. |
{
"type": "object",
"fields": {
"posts": "array of post summary objects",
"total_returned": "integer"
},
"sample": {
"posts": [
{
"city": "تهران",
"title": "سامسونگa07بنفش پک چین",
"token": "Qa0ndl5h",
"district": "آذری",
"has_chat": true,
"red_text": "پله شده",
"image_url": "https://s100.divarcdn.com/static/photo/neda/webp_thumbnail/mwCrBQIeHkxQrSBiR7_qLw/8d89d358-f70d-4e31-96a9-96d5d6a6f75b.webp",
"image_count": 2,
"top_description": "نو",
"bottom_description": "در آذری",
"middle_description": "۲۲,۰۰۰,۰۰۰ تومان"
}
],
"total_returned": 5
}
}About the Divar API
Search and Browse Listings
search_posts accepts three optional filters: a city slug (e.g. tehran, mashhad, tabriz), a category slug (e.g. personal, clothing-a, or ROOT for all categories), and a free-text query string matched against post titles and descriptions. Results are sorted newest-first and include a summary object per post with title, price text, location label, and image info. A limit parameter controls how many posts are returned. Each summary object carries a token field required by the detail endpoint.
Retrieve Full Listing Details
get_post_details takes a single required token string (obtained from search_posts results) and returns a structured record for that listing. Response fields include title, description, price (integer or null), city, district, status, a properties object of key-value attribute pairs (condition, item type, and other category-specific attributes), an images array with both url and thumbnail_url per image, and a location object with latitude and longitude when available.
Coverage and Scope
City coverage includes the eight slugs explicitly supported: tehran, mashhad, karaj, shiraz, isfahan, ahvaz, tabriz, and kerman. Category filtering uses Divar's own slug system; passing ROOT returns listings across all categories. Posts that have been removed or expired may return a non-active status. The properties object varies by listing category — a vehicle listing will carry different attributes than a real-estate or clothing listing.
The Divar API is a managed, monitored endpoint for divar.ir — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when divar.ir 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 divar.ir 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 price trends for a specific product category in Tehran or Mashhad by periodically calling search_posts
- Build a cross-city price comparison tool using the price field returned by get_post_details
- Aggregate geo-tagged listings using the latitude and longitude in the location object for a map-based classifieds browser
- Track new listings in a category by querying search_posts sorted by newest-first and diffing tokens
- Extract structured item attributes from the properties object to populate a product database
- Collect thumbnail and full-resolution image URLs from the images array for visual listing previews
- Feed listing titles and descriptions into a search index for a localized Iranian classifieds aggregator
| 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.