Auto-Doc APIauto-doc.pt ↗
Identify Portuguese-registered vehicles by plate or VIN, then retrieve compatible spare-part categories and priced part listings from auto-doc.pt.
What is the Auto-Doc API?
The auto-doc.pt API provides 3 endpoints that cover the full lookup-to-purchase research flow on AUTODOC Portugal: resolve a Portuguese registration plate or VIN into a verified vehicle record, retrieve the ~500 spare-part categories available for that vehicle, and page through priced part listings with specifications and ratings. The lookup_vehicle endpoint returns structured make, model, variant, and numeric site identifiers that chain directly into the downstream catalogue and parts endpoints.
curl -X GET 'https://api.parse.bot/scraper/a40e810c-8ec4-427f-a8bf-1a311e404d42/lookup_vehicle?plate=12-AB-34' \ -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 auto-doc-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.
"""Walkthrough: AUTODOC Portugal — identify a car by plate, browse categories, list parts."""
from parse_apis.auto_doc_pt_api import AutoDoc, PartsSort, InputNotFound
client = AutoDoc()
# Look up a vehicle from its Portuguese registration plate.
try:
vehicle = client.vehicles.lookup(plate="12-AB-34")
except InputNotFound:
print("Plate not recognised by AUTODOC")
raise
print(vehicle.make, vehicle.model, vehicle.variant) # e.g. BMW 3 Cabrio (E36) 320 i
print(vehicle.title)
print("Engine codes:", vehicle.engine_codes)
# Browse compatible spare-part categories for this vehicle.
category = vehicle.categories.list(limit=5).first()
if category is not None:
print(category.name, f"(group: {category.group})")
# List parts in that category, cheapest first.
for part in vehicle.parts.list(
category_id=str(category.category_id),
sort=PartsSort.PRICE_ASC,
limit=3,
):
print(
part.name,
f"{part.price} {part.currency}",
f"rating={part.rating}",
f"fits={part.fits_vehicle}",
)
print("exercised: vehicles.lookup / categories.list / parts.list")
Identifies a vehicle from a Portuguese registration plate (or a 17-character VIN) using the site's registry lookup, and returns make, model and variant together with the identifiers needed by the other endpoints. One plate lookup is one site-side verification plus three page/panel requests, so it is comparatively slow (several seconds). Exactly one of plate or vin must be given. When the site knows the vehicle, the response carries make, model_series, model (model generation, e.g. '3 Cabrio (E36)'), variant (engine/trim, e.g. '320 i'), fuel, power in hp and kW, production years, engine codes, the numeric make_id/model_id/car_id, and vehicle_path — the identifier to pass to list_part_categories and list_parts. A plate lookup additionally reads the site's 'Dados do veículo' (vehicle data) panel for the vehicle it just resolved and returns the VIN displayed there as vin (a 17-character string); vin is null when the panel shows no VIN, when the panel cannot be loaded, or when the plate shown in the panel is not the plate that was looked up. The VIN is only ever copied from the site; it is never derived or substituted. When the plate matches several vehicles the site returns a candidate list instead; this is exposed as multiple_matches=true with candidates[] (car_id, vehicle_path, title) but no such plate was observed during the build, so that shape is unverified. A plate or VIN the site does not know returns a stale_input error (input_not_found). The VIN input route is accepted by the site but no VIN resolved to a vehicle during the build; only its not-found answer is verified, and on that route the vin key echoes the input.
| Param | Type | Description |
|---|---|---|
| vin | string | 17-character vehicle identification number (letters except I, O, Q and digits). Alternative to plate; not used when plate is given. Only the not-found answer of this route was observed during the build. |
| plate | string | Portuguese registration plate, hyphenated or not (one shape: 12-AB-34). Letters, digits, spaces and hyphens, up to 11 characters; case-insensitive. Required unless vin is given. |
{
"type": "object",
"fields": {
"vin": "17-character VIN displayed in the site's vehicle data panel for the plate that was looked up; null when the site shows none (plate lookups only)",
"fuel": "fuel type label in Portuguese as shown by the site; null when the heading could not be parsed",
"make": "make name as shown by the site",
"model": "model generation / body name",
"plate": "the normalised plate that was looked up (present when the lookup was by plate; vin otherwise)",
"title": "full vehicle heading from the site",
"car_id": "numeric site identifier of the exact vehicle variant",
"make_id": "numeric site identifier of the make",
"variant": "engine / trim designation",
"year_to": "last production year; null when still in production or not parsed",
"model_id": "numeric site identifier of the model series",
"power_hp": "engine power in hp (cv); null when not parsed",
"power_kw": "engine power in kW; null when not parsed",
"make_slug": "URL slug of the make",
"year_from": "first production year; null when not parsed",
"model_slug": "URL slug of the model series",
"vehicle_url": "the vehicle's catalogue page on the site",
"engine_codes": "list of engine codes",
"model_series": "model series name (e.g. 'Série 3')",
"vehicle_path": "vehicle identifier accepted by list_part_categories and list_parts (make/model/generation/car_id-variant)"
},
"sample": {
"data": {
"vin": "WBABJ31010ER16661",
"fuel": "Gasolina",
"make": "BMW",
"model": "3 Cabrio (E36)",
"plate": "12-AB-34",
"title": "Peças BMW 3 Cabrio (E36) 320 i Gasolina 150 cv / 110 kW 1993 - 1999 M50 B20 (206S2)",
"car_id": 302,
"make_id": 16,
"variant": "320 i",
"year_to": 1999,
"model_id": 434,
"power_hp": 150,
"power_kw": 110,
"make_slug": "bmw",
"year_from": 1993,
"model_slug": "3er-reihe",
"vehicle_url": "https://www.auto-doc.pt/pecas-automoveis/bmw/3er-reihe/3-cabriolet-e36/302-320-i",
"engine_codes": [
"M50 B20 (206S2)"
],
"model_series": "Série 3",
"vehicle_path": "bmw/3er-reihe/3-cabriolet-e36/302-320-i"
},
"status": "success"
}
}About the Auto-Doc API
Vehicle Identification
The lookup_vehicle endpoint accepts either a Portuguese registration plate (formatted as 12-AB-34, with or without hyphens) or a 17-character VIN. It returns make, model, variant, and fuel as they appear on the site, along with the full title heading and three numeric identifiers — car_id, make_id, and model_id — that uniquely address the vehicle variant. It also returns a vehicle_path string (for example, bmw/3er-reihe/3-cabriolet-e36) that is required by both other endpoints. When year_to is null the vehicle is either still in production or the production end date could not be determined.
Part Categories
Passing vehicle_path to list_part_categories returns the full category tree for that vehicle — typically around 500 leaf categories grouped under approximately 35 top-level groups such as brakes, filters, and suspension. Each entry in the categories array includes category_id (which you pass to list_parts), name, slug, parent_id, group_id, and group. The count field reports how many categories were returned, and the car_id is echoed back so you can confirm which vehicle variant was queried.
Parts Listing
The list_parts endpoint accepts vehicle_path and a category_id from the category array and returns up to 20 parts per page. Each item in the items array includes article_id, article_number, name, description, generic_name, brand_id, price, currency, price_quantity, recommended retail price, discount percentage where shown, rating, and review_count, plus a full spec_table of technical specifications. Use the page parameter to step through results and check has_more to determine whether further pages exist. The total field reflects the site-reported count for that category and vehicle; it is null when the site does not display a total.
The Auto-Doc API is a managed, monitored endpoint for auto-doc.pt — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when auto-doc.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 auto-doc.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?+
- Build a plate-to-price lookup tool for Portuguese vehicle owners searching for compatible brake pads or filters.
- Aggregate spare-part pricing across categories for a given vehicle to compare against other suppliers.
- Index the full part catalogue for a specific car variant using
list_part_categoriesand paginatedlist_partscalls. - Display OEM article numbers and brand identifiers from
list_partsto cross-reference parts across catalogues. - Track rating and review count trends for specific part categories over time.
- Resolve an unknown VIN to make, model, and variant metadata for use in a fleet management database.
- Populate an autocomplete or vehicle selector using
car_id,make_id, andmodel_idreturned bylookup_vehicle.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does auto-doc.pt offer an official developer API?+
What does `lookup_vehicle` return beyond make and model?+
lookup_vehicle returns make, model, variant, fuel, year_to, the full title heading, and three numeric identifiers — car_id, make_id, and model_id — plus a vehicle_path string required by list_part_categories and list_parts. When year_to is null, either the vehicle is still in production or the end year could not be parsed from the site.How does pagination work in `list_parts`?+
list_parts response contains up to 20 items. Use the page parameter (1-based) to move through results. The has_more boolean tells you whether a subsequent page exists, and total reflects the site-reported part count for that category and vehicle (null when not shown by the site).Can I search for parts by brand or filter by price range?+
list_parts endpoint supports a sort parameter for ordering results but does not currently expose brand or price-range filters as query inputs. It returns brand_id, price, and discount fields in each item, so client-side filtering is possible. You can fork this API on Parse and revise it to add server-side filter parameters if the underlying category pages support them.Does the API cover vehicles registered outside Portugal?+
lookup_vehicle endpoint is built around Portuguese registration plate format (12-AB-34). VIN lookup is also accepted, but coverage is determined by what the auto-doc.pt registry recognises. Non-Portuguese plates are not a supported input. You can fork the API on Parse and revise it to target a different AUTODOC regional site if you need plates from another country.