List APIlist.am ↗
Access List.am vehicle, parts, and accessories listings via API. Search, filter by brand/model/year/price, get full listing details, and retrieve seller contacts.
What is the List API?
The List.am API provides 6 endpoints for querying the Armenian List.am marketplace, covering passenger car listings, auto parts, wheels and tires, and other vehicle categories. get_listing_detail returns up to a dozen structured fields per listing including attributes, images, seller name, and posted date, while get_car_listings_filtered lets you narrow passenger car results by brand, model, year range, price range, and currency.
curl -X GET 'https://api.parse.bot/scraper/2f767f08-e4c0-4261-8441-79aab74876c4/get_category_listings?page=1&query=Toyota&category_id=687' \ -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 list-am-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: List.am API — browse categories, search, filter, and inspect listings."""
from parse_apis.list_am_api import ListAm, Currency, ListingNotFound
client = ListAm()
# List available vehicle categories
for cat in client.categories.list(limit=5):
print(cat.id, cat.name)
# Search for Toyota listings across the marketplace
for listing in client.listings.search(query="Toyota", limit=5):
print(listing.title, listing.price, listing.location)
# Browse a specific category (Passenger Cars = 687)
cars = client.category(id="687")
item = cars.listings(query="BMW", limit=1).first()
# Drill into the listing's full details
if item:
full = item.details()
print(full.title, full.price, full.currency)
print(full.seller_name, full.posted_date)
for key, value in full.attributes.items():
print(key, value)
# Filter car listings by brand (Mercedes-Benz=49) in USD
for car in client.listings.filtered(brand_id="49", currency=Currency.USD, limit=5):
print(car.id, car.title, car.price, car.thumbnail)
# Typed error handling for a non-existent listing
try:
bad = client.listings.search(query="nonexistent_xyz_abc_999", limit=1).first()
except ListingNotFound as exc:
print(f"Listing not found: {exc.item_id}")
print("exercised: categories.list / listings.search / category.listings / details / listings.filtered")
Fetch paginated listings from a specific category. Returns listing summaries including title, price, location, and thumbnail image URL. Supports optional search within the category via query parameter.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for pagination. |
| query | string | Optional search query to filter results within the category. |
| category_idrequired | string | Category ID (e.g. 687 for Passenger Cars, 530 for Car Parts, 238 for Wheels and Tires). |
{
"type": "object",
"fields": {
"page": "string, the current page number",
"listings": "array of listing summary objects with id, url, title, price, location, and thumbnail",
"category_id": "string, the requested category ID"
},
"sample": {
"data": {
"page": "1",
"listings": [
{
"id": "23607862",
"url": "https://www.list.am/en/item/23607862?ld_src=2",
"price": "$19,000",
"title": "2016 Infiniti QX70, 3.7L, all wheel drive",
"location": "Kentron, 2016 y., 125,000 km, Gasoline",
"thumbnail": "https://s.list.am/g/600/96648600.webp"
}
],
"category_id": "687"
},
"status": "success"
}
}About the List API
Category and Search Access
Use get_vehicles_categories to retrieve the full category tree with IDs and nested children — no hard-coding required. Pass any category ID into get_category_listings to get paginated listing summaries, each containing id, url, title, price, location, and a thumbnail image URL. For example, category 687 targets Passenger Cars, 530 targets Car Parts, and 238 targets Wheels and Tires. The optional query parameter on get_category_listings filters results within a category without leaving it.
Search and Filtered Browsing
search_listings accepts a required query keyword and an optional category_id to scope results, returning the same listing summary shape with a page and the echoed query field. For passenger cars specifically, get_car_listings_filtered adds structured filters: brand_id (e.g. 49 for Mercedes-Benz), model_id, year_from, year_to, price_from, price_to, and currency (0 for AMD, 1 for USD). The filters array in the response reflects which parameters were applied.
Listing Detail and Seller Contact
get_listing_detail accepts either an item_id or a full url and returns the complete record: title, price, currency, location, description, posted_date, seller_name, a full images array, and an attributes object mapping labels such as Make, Model, Year, and Engine Type to their values. To retrieve a seller's phone number, pass the item_id to get_phone_number, which returns the phone string for that listing.
The List API is a managed, monitored endpoint for list.am — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when list.am 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 list.am 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 car make and model by polling
get_car_listings_filteredwithbrand_idandmodel_idover time. - Build a cross-listing alert tool that watches
get_category_listingsfor new entries in the Car Parts category (ID 530). - Aggregate seller contact data by combining
get_listing_detailforseller_namewithget_phone_numberfor outreach pipelines. - Populate a vehicle comparison tool using
attributesfields (Make, Model, Year, Engine Type) returned byget_listing_detail. - Sync a local inventory database with current List.am passenger car listings using paginated
get_car_listings_filteredrequests. - Build a currency-aware price dashboard by filtering listings with
currencyset to AMD or USD and tracking thepricefield. - Index List.am listing images for a visual search tool using the
imagesarray fromget_listing_detail.
| 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 List.am have an official developer API?+
What does `get_car_listings_filtered` return compared to `get_category_listings`?+
get_category_listings returns paginated summaries for any category ID you pass in, with no structured filtering beyond an optional text query. get_car_listings_filtered is scoped to the Passenger Cars category and adds typed filter parameters — brand_id, model_id, year_from, year_to, price_from, price_to, and currency. Its response also includes a filters array showing which parameters were applied. Both return the same listing summary shape: id, url, title, price, location, and thumbnail.Are motorcycles, trucks, or boats covered by the filtering endpoint?+
get_car_listings_filtered is scoped to the Passenger Cars category only. You can reach other vehicle types via get_category_listings using their category IDs from get_vehicles_categories, but without the structured brand/model/year filters. You can fork this API on Parse and revise it to add a filtered endpoint for motorcycles or other vehicle types.Does the API return listing creation or expiry dates?+
get_listing_detail returns a posted_date field for individual listings. Listing summaries returned by get_category_listings, search_listings, and get_car_listings_filtered do not include dates — only id, url, title, price, location, and thumbnail. If you need date filtering on summary results, you can fork this API on Parse and revise to add that field to the summary response.Is there a known limitation with phone number retrieval?+
get_phone_number endpoint requires Cloudflare clearance to resolve successfully. Requests may fail or return incomplete data in environments where that clearance cannot be established. Other endpoints do not have this restriction.