OpenSooq APIjo.opensooq.com ↗
Access classified listings, categories, and listing details from OpenSooq Jordan via 4 endpoints. Search by keyword or browse by category slug.
What is the OpenSooq API?
The OpenSooq Jordan API exposes 4 endpoints for browsing and searching classified listings on jo.opensooq.com, Jordan's largest classifieds marketplace. Starting with get_categories to retrieve top-level category slugs, you can then feed those slugs into get_listings_by_category or run free-text queries via search_listings, and pull full listing details — including price, images, location, and seller info — with get_listing_detail.
No input parameters required.
curl -X GET 'https://api.parse.bot/scraper/d8b13845-b2b0-4a24-a8a7-eaa26da5a269/get_categories' \ -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 jo-opensooq-com-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.
from parse_apis.opensooq_jordan_api import OpenSooq, Category, ListingSummary, Listing
client = OpenSooq()
# List all categories
for category in client.categories.list():
print(category.name, category.slug)
# Browse listings in a category using constructible Category
electronics = client.category("electronics")
for listing_summary in electronics.listings.list(limit=5):
print(listing_summary.id, listing_summary.url)
# Search for listings
for result in client.listingsummaries.search(query="Toyota", limit=3):
detail = result.details()
print(detail.title, detail.price, detail.currency, detail.location)
Retrieves all top-level listing categories from the OpenSooq Jordan homepage. Each category has a name, full URL, and a slug usable with get_listings_by_category. The category set is relatively stable (Motors, Property, Jobs, Services, Electronics, etc.) but may shift as OpenSooq reorganizes.
No input parameters required.
{
"type": "object",
"fields": {
"items": "array of category objects each containing name, url, and slug"
},
"sample": {
"data": {
"items": [
{
"url": "https://jo.opensooq.com/en/autos",
"name": "Motors",
"slug": "autos"
},
{
"url": "https://jo.opensooq.com/en/real-estate",
"name": "Property",
"slug": "real-estate"
},
{
"url": "https://jo.opensooq.com/en/electronics",
"name": "Electronics",
"slug": "electronics"
}
]
},
"status": "success"
}
}About the OpenSooq API
Endpoints and Data Coverage
The API is built around four endpoints. get_categories returns every top-level category available on the OpenSooq Jordan homepage as an array of objects with name, url, and slug fields. Those slugs — for example mobile-phones-tablets, cars, or home-garden — are the required input for get_listings_by_category, which returns paginated arrays of listing objects containing id and url. Both get_listings_by_category and search_listings accept an optional page integer for pagination. Note that some legacy category slugs may return a 410 Gone response; use get_categories to confirm valid slugs before passing them to the category endpoint.
Listing Detail Fields
get_listing_detail accepts a numeric listing_id (obtainable from either browse or search results) and returns a single data object with: id, title, price, currency, description, publish_date, images (array), location, and seller. This is the richest response in the API and the appropriate endpoint when you need full item metadata rather than just IDs and URLs.
Search and Browse Workflows
search_listings takes a required query string — suitable for terms like iPhone, Toyota, or apartment — and returns the same paginated id and url structure as the category browse endpoint. This makes it straightforward to build a pipeline: search or browse to collect listing IDs, then call get_listing_detail in sequence to hydrate each result with price, location, and seller data.
The OpenSooq API is a managed, monitored endpoint for jo.opensooq.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when jo.opensooq.com 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 jo.opensooq.com 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 specific product types (e.g. used cars or smartphones) by combining
search_listingswithget_listing_detail. - Build a category map of OpenSooq Jordan by pulling all slugs from
get_categoriesand iteratingget_listings_by_category. - Track new listings in a given category by polling
get_listings_by_categoryand comparingpublish_datefromget_listing_detail. - Aggregate seller activity by collecting
sellerfields from multipleget_listing_detailresponses. - Extract location distribution of listings across Jordan by reading the
locationfield at scale. - Build a price comparison tool for specific search terms using
search_listingspluspriceandcurrencyfromget_listing_detail. - Collect training data for a classifieds recommendation model using category, title, description, and image fields.
| 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 OpenSooq have an official developer API?+
What does `get_listing_detail` return beyond basic price and title?+
get_listing_detail returns id, title, price, currency, description, publish_date, an images array, location, and seller information. It does not return bidding history, view counts, or contact phone numbers. You can fork the API on Parse and revise it to add additional fields if they become accessible.Does the API cover subcategories, not just top-level categories?+
get_categories returns top-level categories only, and get_listings_by_category accepts top-level slugs. Subcategory browsing is not covered. You can fork the API on Parse and revise it to add a subcategory endpoint.Are there any known quirks with category slugs?+
get_listings_by_category. Always retrieve current slugs from get_categories before using them, rather than hardcoding slugs from external sources.