Divar Api

Use this skill whenever the user wants to search, query, or extract data from Divar (divar.ir) — Iran's largest classifieds platform. Triggers include: searc...

Security Scan

The skill is an instruction-only reference for Divar.ir's widget-based API and its requested resources and behavior align with that purpose (no installs, no secrets requested), but review the authentication guidance carefully and inspect the files for hidden control characters before supplying any session tokens or cookies.

Purpose & Capability

Name and description (Divar API/search/extract) match the provided SKILL.md and supplementary docs. All endpoints, payload formats, and examples are consistent with a documentation/scraping helper for divar.ir; there are no unrelated credentials, binaries, or install actions requested.

Instruction Scope

The SKILL.md gives detailed instructions for building search/detail/contact requests and documents authentication mechanisms (cookie + did, Authorization header). It does not itself request environment variables or tell the agent to read system files, but it does explain how to use session cookies/JWTs to fetch contact info. Because authenticated contact retrieval requires user session data, the user should not paste or expose Divar cookies/JWTs into the chat unless they understand the risk.

Install Mechanism

Instruction-only skill with no install spec and no code files — nothing will be written to disk or downloaded during installation.

Credentials

The skill declares no required environment variables, credentials, or config paths. The only sensitive items mentioned are Divar session cookies/JWTs needed for authenticated endpoints; those are expected for the described functionality but are not requested by the skill itself.

Persistence & Privilege

always is false and the skill does not request elevated or persistent system privileges. Autonomous invocation is allowed (platform default) but does not combine here with broad credentials or install behavior.

Scan Findings in Context

[unicode-control-chars] unexpected: The static scanner detected unicode control characters in SKILL.md. This is not expected for a plain API doc; such characters can be used to hide or obfuscate text (prompt-injection attempts). The visible content appears legitimate, but you should manually inspect the raw files or view with a hex/visible-control-char tool before trusting any embedded instructions that might be hidden.

Assessment

This skill is a documentation-only helper for Divar's public/internal API and appears internally consistent. Before using it: 1) Do not paste your Divar session cookies, JWTs, or other secrets into the chat unless you explicitly want the agent to make authenticated requests on your behalf — sharing these gives full access to authenticated endpoints (contact info, user-specific data). 2) Manually inspect the SKILL.md/README for invisible control characters (the scanner flagged unicode-control-chars) or other hidden text. 3) Remember scraping or automating Divar may trigger rate limits, bot detection, or violate terms of service — respect robots and legal restrictions. 4) If you need contact info from authenticated endpoints, prefer to perform the authenticated request yourself (outside the skill) and paste only the non-sensitive results back into the agent. If you are not comfortable with these checks, do not install or use the skill.

Divar API Skill

Divar uses a server-driven widget API (JSON over HTTPS, protobuf type annotations embedded via @type). All responses are lists of typed widget_type objects. Base URL: https://api.divar.ir.

Critical: form_data field types

Every filter field uses a typed wrapper. Wrong type = HTTP 400. Use this table exactly:

Field	Wrapper	Example
category	str	{ "str": { "value": "residential-rent" } }
sort	str	{ "str": { "value": "sort_date" } }
districts	repeated_string	{ "repeated_string": { "value": ["920", "82"] } }
rooms	repeated_string	{ "repeated_string": { "value": ["یک", "دو"] } }
rent	number_range	{ "number_range": { "minimum": "20000000", "maximum": "60000000" } }
credit	number_range	{ "number_range": { "minimum": "300000000", "maximum": "600000000" } }
size	number_range	{ "number_range": { "minimum": "80", "maximum": "120" } }
balcony	boolean	{ "boolean": { "value": true } }
parking	boolean	{ "boolean": { "value": true } }

number_range min/max values are strings, not numbers. boolean value is a JS boolean (true/false), not a string.

Critical: category slugs

The API slug differs from the divar.ir URL path segment. Never use the URL segment as the slug.

API slug (category.str.value)	URL path	Persian
residential-rent	rent-residential	اجاره مسکونی
apartment-sell	apartment-sell	فروش آپارتمان
apartment-rent	rent-apartment	اجاره آپارتمان
buy-residential	buy-residential	فروش مسکونی
real-estate	real-estate	همه ملک
buy-commercial-property	buy-commercial-property	فروش اداری/تجاری
rent-commercial-property	rent-commercial-property	اجاره اداری/تجاری
rent-temporary	rent-temporary	اجاره کوتاه‌مدت

When in doubt, intercept a real browser request via DevTools to read the actual category.str.value.

Search endpoint

POST /v8/postlist/w/search

Verified working payload (residential rental, Tehran, tested 2026-04-01 → returned 24 listings):

{
  "city_ids": ["1"],
  "source_view": "SEARCH",
  "disable_recommendation": false,
  "search_data": {
    "form_data": {
      "data": {
        "category":  { "str":            { "value": "residential-rent" } },
        "districts": { "repeated_string": { "value": ["139","143","145","4162","75","78","82","920","921"] } },
        "rooms":     { "repeated_string": { "value": ["دو","یک"] } },
        "rent":      { "number_range":   { "minimum": "20000000",  "maximum": "60000000"  } },
        "credit":    { "number_range":   { "minimum": "300000000", "maximum": "600000000" } },
        "size":      { "number_range":   { "minimum": "80",        "maximum": "120"       } },
        "balcony":   { "boolean":        { "value": true } },
        "parking":   { "boolean":        { "value": true } }
      }
    },
    "server_payload": {
      "@type": "type.googleapis.com/widgets.SearchData.ServerPayload",
      "additional_form_data": {
        "data": { "sort": { "str": { "value": "sort_date" } } }
      }
    }
  }
}

Response: { "list_top_widgets": [...], "list_widgets": [...] }

Filter to widget_type === "POST_ROW" to get listings. Each POST_ROW has:

• data.title — listing title (Persian)
• data.middle_description_text — price string
• data.bottom_description_text — relative time ("دقایقی پیش")
• data.action.payload.token — unique post ID (use for detail/contact endpoints)
• data.action.payload.web_info.district_persian — district name
• data.image_count — number of photos

Pagination

Cursor-based. On page 1, no pagination_data. On page 2+, add:

{
  "pagination_data": {
    "@type": "type.googleapis.com/post_list.PaginationData",
    "last_post_date": "<ISO8601 from previous last post>",
    "page": 2,
    "layer_page": 2,
    "search_uid": "<uuid — keep constant for the session>",
    "cumulative_widgets_count": 24
  }
}

viewed_tokens is an optional gzip+base64 bloom filter for server-side deduplication — safe to omit.

Post detail

GET /v8/posts-v2/web/{token}

Returns sections (BREADCRUMB, HEADER, IMAGES, DETAILS) each containing widget arrays. Common detail widget types: KEY_VALUE (room count, floor, etc.), DESCRIPTION, IMAGE_GALLERY, MAP.

Contact info (requires auth)

POST /v8/postcontact/web/contact_info_v2/{token}

Body: {}. Returns widget_list with UNEXPANDABLE_ROW containing phone number. Returns RBAC: access denied without authentication.

Authentication

• Cookie-based: token cookie + did (device ID) cookie, set by divar.ir on login.
• Header: Authorization: Basic <jwt> — same JWT value as the token cookie.
• The search endpoint works with session cookies alone when called same-origin from divar.ir.
• Cross-origin calls (e.g. from a script) need the Authorization header explicitly.

Parsing a divar.ir search URL → API payload

When a user pastes a URL like: https://divar.ir/s/tehran/rent-residential/almahdi?balcony=true&credit=300000000-600000000&districts=920%2C82&rent=20000000-60000000&rooms=%D8%AF%D9%88%2C%DB%8C%DA%A9&size=80-120

Map query params to form_data fields:

URL param	form_data field	Wrapper
URL path segment (e.g. rent-residential)	category → look up API slug	str
districts=920,82,...	districts	repeated_string (split on ,)
rooms=دو,یک	rooms	repeated_string (split on ,)
rent=min-max	rent	number_range (split on -)
credit=min-max	credit	number_range (split on -)
size=min-max	size	number_range (split on -)
balcony=true	balcony	boolean
parking=true	parking	boolean
map_bbox=...	not in form_data — belongs in /v8/mapview/viewport camera_info.bbox	—
map_place_hash=...	not in form_data	—

For full API reference (all endpoints, widget system, map/geo, autocomplete, filters): → read references/api-reference.md