OLX APIolx.pt ↗
Access OLX.pt listings via API. Search by keyword, price, region, and category. Get full listing details including price, photos, seller info, and location.
What is the OLX API?
The OLX Portugal API provides 3 endpoints to search, retrieve, and categorize listings from olx.pt. The search_listings endpoint accepts filters for keyword, price range, region, city, and sort order, returning paginated arrays of listing objects with fields including id, url, title, description, params (price), location, photos, user, and category. Whether you need broad market sweeps or deep detail on a single ad, the API covers the full retrieval workflow.
curl -X GET 'https://api.parse.bot/scraper/c81a1506-5f37-453f-b82b-552abb8ca36e/search_listings?limit=5&query=iphone&offset=0&sort_by=created_at%3Adesc' \ -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 olx-pt-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.olx_portugal_scraper_api import OLX, Sort
olx = OLX()
# List available categories
for category in olx.categories.list(limit=10):
print(category.id)
# Search listings sorted by price
for listing in olx.listings.search(query="apartamento", sort_by=Sort.CHEAPEST, limit=5):
print(listing.id, listing.title, listing.created_time)
# Get detailed info for a specific listing
detail = olx.listings.get(listing_id="671304208")
print(detail.title, detail.url, detail.status)
Search for listings on OLX.pt with various filters. Returns paginated results sorted by the specified order. Pagination is offset-based: advance by incrementing offset by limit. Each listing includes id, title, price params, location, photos, seller info, and category. When called without a query or filters, returns the most recent listings across all categories. The metadata object reports total_elements for the query.
| Param | Type | Description |
|---|---|---|
| limit | integer | Maximum number of results to return per page. |
| query | string | Search keyword (e.g. 'apartamento', 'iphone'). Omitting returns all listings. |
| offset | integer | Pagination offset (number of results to skip). |
| city_id | string | City ID for location filtering. |
| sort_by | string | Sorting order. |
| price_max | string | Maximum price filter in EUR. |
| price_min | string | Minimum price filter in EUR. |
| region_id | string | Region ID for location filtering (e.g. '13' for Porto, '1' for Lisbon). |
| category_id | string | Category ID for filtering. Use get_categories to discover valid IDs. |
{
"type": "object",
"fields": {
"data": "array of listing objects, each containing id, url, title, description, params (including price), location, photos, user, category, and timestamps",
"metadata": "object with total_elements, visible_total_count, promoted indices, and search_id"
},
"sample": {
"data": {
"data": [
{
"id": 671304208,
"url": "https://www.olx.pt/d/anuncio/peugeot-308-1-2-puretech-allure-eat8-IDJqITe.html",
"user": {
"id": 215452325,
"name": "Ricardo manso"
},
"title": "Peugeot 308 1.2 PureTech Allure EAT8",
"params": [
{
"key": "price",
"name": "Preço",
"type": "price",
"value": {
"label": "18.990 €",
"value": 18990,
"currency": "EUR"
}
}
],
"photos": [
{
"id": 3580745798,
"link": "https://ireland.apollo.olxcdn.com:443/v1/files/li2pssrb6c031-PT/image;s={width}x{height}",
"filename": "li2pssrb6c031-PT"
}
],
"category": {
"id": 613,
"type": "automotive"
},
"location": {
"city": {
"id": 10495014,
"name": "Santa Catarina Da Serra E Chainça"
},
"region": {
"id": 10,
"name": "Leiria"
}
},
"description": "Este compacto Peugeot 308...",
"created_time": "2026-06-01T11:50:48+01:00",
"last_refresh_time": "2026-06-10T10:15:37+01:00"
}
],
"metadata": {
"search_id": "62DD0963084CD289525A189A2666293C",
"total_elements": 1000,
"visible_total_count": 3722072
}
},
"status": "success"
}
}About the OLX API
Endpoints and Data Coverage
The API exposes three endpoints. search_listings is the primary entry point, accepting optional inputs like query, region_id, city_id, price_min, price_max, sort_by, limit, and offset. Region IDs are numeric strings — for example, '13' for Porto and '1' for Lisbon. Sorting supports four modes: created_at:desc, created_at:asc, price:asc, and price:desc. Called without any filters, it returns the most recently posted listings across all categories, which is useful for feed-style monitoring.
Listing Response Shape
Each listing object returned by search_listings contains id, url, title, description, params (which holds price and any structured attributes), location, photos, user, and category. The metadata field alongside the array includes total_elements, visible_total_count, promoted indices, and a search_id useful for paginating large result sets via the offset parameter.
Detailed Listing and Category Discovery
get_listing_details accepts a listing_id (the numeric ID from search_listings results) and returns the full listing record, including extended params such as year, model, and other attribute fields that vary by category. get_categories takes no inputs and returns an array of integer category IDs currently enabled on olx.pt — these IDs can be passed as category_id in search_listings to scope searches to a specific vertical like real estate, vehicles, or electronics.
The OLX API is a managed, monitored endpoint for olx.pt — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when olx.pt 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 olx.pt 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 newly posted real estate listings in Lisbon or Porto by polling
search_listingssorted bycreated_at:descwith the appropriateregion_id. - Build a price-comparison tool for a specific product category by filtering
search_listingswithquery,price_min, andprice_max. - Track seller activity by extracting the
userfield from listing objects returned across multiple searches. - Aggregate market pricing data for a given category by iterating paginated results using
limitandoffset. - Enrich a listing dataset with full attribute details (year, model, extended params) by calling
get_listing_detailson IDs gathered from search. - Discover all active category IDs on olx.pt using
get_categoriesbefore building a category-scoped crawl pipeline. - Alert on vehicle listings below a price threshold by combining
sort_by: price:ascwithprice_maxinsearch_listings.
| 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 OLX Portugal have an official developer API?+
How does pagination work in `search_listings`?+
limit parameter to set results per page and offset to skip results. The metadata object in the response includes total_elements and visible_total_count, which tell you the full result set size so you can calculate how many pages to request.Does the API return seller contact details such as phone numbers?+
user field in listing objects contains seller profile information, but phone numbers and other contact details that OLX gates behind a login or click-to-reveal action are not exposed. The API covers publicly visible listing and seller profile data. You can fork this API on Parse and revise it to add an endpoint targeting contact-reveal responses if that data becomes accessible in your use case.Is there a way to filter searches by category?+
get_categories first to retrieve the array of enabled integer category IDs on olx.pt, then pass the desired ID as category_id in search_listings. This scopes results to a single vertical, such as real estate or vehicles.