{ "openapi": "3.1.0", "info": { "title": "PlateAPI", "version": "1.0.0", "description": "Australian vehicle registration plate lookup API. Send a plate number and state, get structured vehicle data back as JSON. Covers all eight Australian states and territories.", "contact": { "name": "PlateAPI Support", "email": "support@plateapi.com.au", "url": "https://plateapi.com.au/contact/" }, "x-logo": { "url": "https://plateapi.com.au/logo.jpg" } }, "servers": [ { "url": "https://api.plateapi.com.au", "description": "Production" } ], "security": [ { "ApiKeyAuth": [] } ], "paths": { "/api/v1/lookup": { "get": { "operationId": "lookupPlate", "summary": "Look up a vehicle by registration plate", "description": "Returns structured vehicle data (year range, make, model, body type, engine displacement) for an Australian registration plate.", "parameters": [ { "name": "plate", "in": "query", "required": true, "description": "Registration plate number (e.g. ABC123). Case-insensitive. Letters, numbers, dashes, and spaces only, maximum 10 characters. The sandbox plate TEST123 returns a fixed response instantly with no quota or rate-limit cost.", "schema": { "type": "string", "maxLength": 10, "example": "ABC123" } }, { "name": "state", "in": "query", "required": true, "description": "Australian state or territory code.", "schema": { "type": "string", "enum": [ "ACT", "NSW", "NT", "QLD", "SA", "TAS", "VIC", "WA" ], "example": "VIC" } }, { "name": "detailed", "in": "query", "required": false, "description": "Set to true to include detailed_description in the vehicle object. This field contains extended vehicle data (chassis codes, drivetrain, fuel type, engine code, power output) when available. May return null for some vehicles.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Lookup result. Check the success field to determine if a vehicle was found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LookupResponse" }, "examples": { "found": { "summary": "Vehicle found", "value": { "success": true, "vehicle": { "year_range": "2003-2006", "lowest_year": 2003, "highest_year": 2006, "make": "TOYOTA", "model": "COROLLA", "description": "03~06 TOYOTA COROLLA SPORTIVO 1.8L PETROL", "body": "HATCHBACK", "engine": "1.8L", "vehicle_id": 5152708 }, "source": "plateapi", "duration_ms": 1509.96, "alternatives": [ { "year_range": "2003-2006", "lowest_year": 2003, "highest_year": 2006, "make": "TOYOTA", "model": "COROLLA", "description": "03~06 TOYOTA COROLLA ASCENT 1.8L PETROL", "body": "SEDAN", "engine": "1.8L", "vehicle_id": 1857621 } ], "match": "multiple" } }, "not_found": { "summary": "Vehicle not found", "value": { "success": false, "vehicle": null, "code": "not_found", "error": "Vehicle not found. Check your plate and try again.", "duration_ms": 4521.33, "request_id": "req_2c1d9e7a4b3f8e6d0a1b" } } } } } }, "400": { "description": "Invalid request (missing or invalid parameters)" }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "The request comes from an IP address that is not on the key's IP allowlist, or the account is banned", "content": { "application/json": { "examples": { "ip_allowlist": { "summary": "IP address not on the key's allowlist", "value": { "detail": "This API key is not allowed from your IP address." } }, "banned": { "summary": "Banned account", "value": { "detail": "This account has been permanently banned for violating our Terms of Service." } } } } } }, "429": { "description": "Per-minute rate limit exceeded (sliding 60-second window; Retry-After 1-60) or monthly quota exhausted (Retry-After: 3600)", "headers": { "Retry-After": { "description": "Seconds to wait before retrying: for the per-minute limit, the seconds until the oldest request in the 60-second window expires (1-60); 3600 for an exhausted monthly quota", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "rate_limit": { "summary": "Per-minute rate limit", "value": { "detail": "Per-minute rate limit exceeded (10/min on starter plan). Slow down." } }, "quota_exceeded": { "summary": "Monthly quota exhausted", "value": { "detail": "Monthly quota exceeded. Used 600/600 lookups on starter plan. Upgrade at plateapi.com.au" } } } } } }, "503": { "description": "The lookup could not be completed right now (code lookup_failed, not billed; retry after a few seconds), or the service is briefly unavailable (Retry-After header set)", "content": { "application/json": { "examples": { "lookup_failed": { "summary": "Lookup could not be completed", "value": { "success": false, "vehicle": null, "code": "lookup_failed", "error": "Lookup temporarily unavailable. Please retry.", "duration_ms": 6012.4, "request_id": "req_9b2e4c1d7a3f5e8b0c6d2a4f" } }, "service_unavailable": { "summary": "Service briefly unavailable (Retry-After set)", "value": { "detail": "Service temporarily unavailable. Please retry." } } } } } } } } }, "/api/v1/keys/usage": { "get": { "operationId": "getKeyUsage", "summary": "Check quota and plan details", "description": "Returns your current plan, quota usage, rate limit, billing period, and last lookup timestamp.", "parameters": [ { "name": "X-API-Key", "in": "header", "required": true, "description": "Your API key.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Usage details", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "plan": { "type": "string", "enum": [ "free", "lite", "starter", "growth", "enterprise", "starter_legacy", "starter_legacy2", "growth_legacy", "growth_legacy2", "enterprise_legacy", "enterprise_plus" ] }, "monthly_limit": { "type": "integer" }, "used_this_month": { "type": "integer" }, "remaining": { "type": "integer" }, "percent_used": { "type": [ "number", "null" ] }, "rate_limit_per_min": { "type": "integer" }, "last_lookup_at": { "type": [ "string", "null" ] }, "period_start": { "type": [ "string", "null" ] }, "period_end": { "type": [ "string", "null" ] }, "days_remaining": { "type": [ "integer", "null" ], "description": "Null whenever period_end is null" }, "topup_credits": { "type": "integer", "description": "Purchased top-up lookups remaining" }, "cancel_at_period_end": { "type": "boolean" }, "cancel_at": { "type": [ "string", "null" ] } } } } } }, "401": { "description": "Missing or invalid API key" } } } }, "/api/v1/keys/logs": { "get": { "operationId": "getKeyLogs", "summary": "Lookup history", "description": "Returns a paginated list of your lookup history with optional filtering by time range, plate, and outcome.", "parameters": [ { "name": "X-API-Key", "in": "header", "required": true, "description": "Your API key.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Number of entries to return (max 500).", "schema": { "type": "integer", "default": 100, "maximum": 500 } }, { "name": "offset", "in": "query", "required": false, "description": "Number of entries to skip for pagination.", "schema": { "type": "integer", "default": 0 } }, { "name": "since", "in": "query", "required": false, "description": "Start of time range (ISO 8601, UTC).", "schema": { "type": "string", "example": "2026-07-01T00:00:00" } }, { "name": "until", "in": "query", "required": false, "description": "End of time range (ISO 8601, UTC).", "schema": { "type": "string", "example": "2026-07-31T23:59:59" } }, { "name": "plate", "in": "query", "required": false, "description": "Filter by plate number (case-insensitive).", "schema": { "type": "string" } }, { "name": "success", "in": "query", "required": false, "description": "Filter by outcome (true for found, false for not found).", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Lookup history" }, "401": { "description": "Missing or invalid API key" } } } }, "/api/v1/vehicles": { "get": { "operationId": "queryVehicles", "summary": "Query the vehicle database", "description": "Seven-level cascading query for make/model/year dropdowns. type=car (default) or type=motorcycle selects the cascade; IDs are the same kind in both. Call with no parameters to list makes, then add make, model, year, series, engine and variant one at a time; the last level returns a list of vehicle records, each with a vehicle_id (usually one; fewer than 100 paths return two vehicles whose catalogue entries overlap in that year). Pass every value exactly as returned by the previous level and URL-encode it: values contain commas, double spaces, braces, brackets and slashes, and matching is exact including letter case, so make=toyota or a collapsed double space returns an empty list. An empty-string series is a real value; send series= (empty) to continue. Unknown values return 200 with an empty data list, not an error. vehicle_id is a stable ID for the variant (the same for every model year it was sold) and is the same ID /api/v1/lookup returns. Requires a Starter-or-above API key (Free and Lite get 403). Does not count toward the monthly lookup quota. 500 requests/minute rate limit. Keep the API key on your server, not in browser JavaScript.", "parameters": [ { "name": "type", "in": "query", "required": false, "description": "Which cascade: car (default, the car cascade) or motorcycle (motorcycles, scooters, ATVs, snowmobiles). Any other value returns 400.", "schema": { "type": "string", "enum": [ "car", "motorcycle" ], "default": "car" } }, { "name": "make", "in": "query", "required": false, "description": "Manufacturer name exactly as returned by the makes list (e.g. TOYOTA).", "schema": { "type": "string", "example": "TOYOTA" } }, { "name": "model", "in": "query", "required": false, "description": "Model name. Requires make.", "schema": { "type": "string", "example": "HILUX" } }, { "name": "year", "in": "query", "required": false, "description": "Model year. Requires make and model.", "schema": { "type": "integer", "example": 2019 } }, { "name": "series", "in": "query", "required": false, "description": "Series/chassis code as returned by the series list. Can be an empty string for vehicles without a series code. Requires make, model, and year.", "schema": { "type": "string", "example": "GUN126R -GUN126" } }, { "name": "engine", "in": "query", "required": false, "description": "Engine description as returned by the engines list. Requires all previous parameters.", "schema": { "type": "string", "example": "2.8L, DIE 1GDFTV I4 16v DOHC I/C Turbo CRD {130kW}" } }, { "name": "variant", "in": "query", "required": false, "description": "Variant name (select_text) as returned by the variants list. Requires all previous parameters. Returns full vehicle records for this specific variant.", "schema": { "type": "string", "example": "4D Ute -, 4WD MR0HA3CD [THAILAND], AT/MT" } } ], "responses": { "200": { "description": "Vehicle database query result. The type field indicates the cascade level: make, model, year, series, engine, variant, or vehicle.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VehiclesResponse" }, "examples": { "makes": { "summary": "List of makes (no parameters)", "value": { "success": true, "data": [ { "type": "make", "data": [ "ABARTH", "ACE EV", "ACURA", "ALEXANDER DENNIS", "ALFA ROMEO", "ALPINE" ] } ], "total": 227, "duration_ms": 2.81 } }, "variants": { "summary": "Variant names (Toyota Hilux 2019, series GUN126R -GUN126, engine 2.8L, DIE 1GDFTV I4 16v DOHC I/C Turbo CRD {130kW})", "value": { "success": true, "data": [ { "type": "variant", "data": [ "4D Ute -, 4WD MR0HA3CD [THAILAND], AT/MT" ] } ], "total": 1, "duration_ms": 0.69 } }, "vehicle": { "summary": "Full vehicle records (all parameters including variant provided)", "value": { "success": true, "data": [ { "type": "vehicle", "data": [ { "vehicle_id": 1346446, "select_text": "4D Ute -, 4WD MR0HA3CD [THAILAND], AT/MT", "description": "15~20 TOYOTA HILUX 2.8L DIESEL", "long_description": "TOYOTA HILUX 10/2015~04/2020" } ] } ], "total": 1, "duration_ms": 1.58 } }, "empty": { "summary": "Unknown or mismatched value (not an error)", "value": { "success": true, "data": [ { "type": "model", "data": [] } ], "total": 0, "duration_ms": 0.59 } } } } } }, "400": { "description": "Invalid parameter: year is not an integer or is outside 1900-2100, or a text parameter is longer than 200 characters or contains unsupported characters. Body: {\"detail\": \"Invalid query parameters. ...\"}" }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Starter plan or above required (Free and Lite keys get 403)" }, "429": { "description": "Rate limit exceeded (500 requests/minute)" }, "503": { "description": "Vehicle database temporarily unavailable (Retry-After header set). Never answered as a 200: a 200 with an empty list always means an unknown value", "content": { "application/json": { "example": { "success": false, "code": "unavailable", "error": "Vehicle database temporarily unavailable. Please retry.", "data": [], "total": 0, "duration_ms": 0.3 } } } } } } }, "/api/v1/vehicles/{vehicle_id}": { "get": { "operationId": "getVehicle", "summary": "Fetch one vehicle by ID", "description": "Returns the vehicle database record for one vehicle_id, as returned by /api/v1/lookup (on vehicle and on each alternatives entry, null when not certain) and by the last level of /api/v1/vehicles. The ID identifies the variant, not the year, and is stable. detail is \"full\" for a complete record or \"basic\" (series, variant and long_description null, years empty) when only the ID and summary fields exist; e.g. 7295503 is a basic record and 1380801 (sandbox plate TEST123) is a full one. Requires a Starter-or-above API key (Free and Lite get 403). Does not count toward monthly lookup quota. Shares the 500 requests/minute vehicle database rate limit. If the requested ID has been merged into another (the database occasionally held one vehicle under two IDs), the response is the current record; compare its vehicle_id with the one requested.", "parameters": [ { "name": "vehicle_id", "in": "path", "required": true, "description": "PlateAPI vehicle ID.", "schema": { "type": "integer", "example": 1380801 } } ], "responses": { "200": { "description": "Vehicle record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VehicleRecordResponse" }, "example": { "success": true, "vehicle": { "vehicle_id": 1380801, "vehicle_type": "car", "make": "TOYOTA", "model": "HILUX SR", "year_range": "2015-2020", "lowest_year": 2015, "highest_year": 2020, "years": [ 2015, 2016, 2017, 2018, 2019, 2020 ], "description": "15~20 TOYOTA HILUX 2.8L DIESEL", "long_description": "TOYOTA HILUX 10/2015~04/2020", "series": "GUN126R -GUN126", "engine": "2.8L, DIE 1GDFTV I4 16v DOHC I/C Turbo CRD {130kW}", "variant": "SR, 4D Ute -, 4WD MR0KA3CD [THAILAND], AT/MT", "body": "UTE", "body_size": null, "doors": 4, "drive": "4WD", "transmission": "AT/MT", "detail": "full" }, "duration_ms": 1.61 } } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Starter plan or above required (Free and Lite keys get 403)" }, "400": { "description": "vehicle_id is not an integer (body: {\"detail\": \"Invalid path parameters. vehicle_id: ...\"})", "content": { "application/json": { "example": { "detail": "Invalid path parameters. vehicle_id: Input should be a valid integer, unable to parse string as an integer" } } } }, "404": { "description": "No vehicle with that vehicle_id", "content": { "application/json": { "example": { "success": false, "vehicle": null, "code": "not_found", "error": "No vehicle with that vehicle_id.", "duration_ms": 0.49 } } } }, "429": { "description": "Rate limit exceeded (500 requests/minute)" }, "503": { "description": "Vehicle database temporarily unavailable (Retry-After header set)", "content": { "application/json": { "example": { "success": false, "vehicle": null, "code": "unavailable", "error": "Vehicle database temporarily unavailable. Please retry.", "duration_ms": 0.3 } } } } } } }, "/api/v1/health": { "get": { "operationId": "healthCheck", "summary": "Health check", "description": "Returns API health status. No authentication required.", "security": [], "responses": { "200": { "description": "API is healthy" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "API key from your PlateAPI dashboard. Free keys start with pk_live_." } }, "schemas": { "Vehicle": { "type": "object", "properties": { "year_range": { "type": "string", "description": "Model year range (e.g. 2003-2006 or 2020-ON for current production)", "example": "2003-2006" }, "lowest_year": { "type": "integer", "description": "First model year of the range", "example": 2003 }, "highest_year": { "type": [ "integer", "null" ], "description": "Last model year of the range. Null for models still in production.", "example": 2006 }, "make": { "type": "string", "description": "Manufacturer name", "example": "TOYOTA" }, "model": { "type": "string", "description": "Model name", "example": "COROLLA" }, "description": { "type": "string", "description": "Full vehicle description string", "example": "03~06 TOYOTA COROLLA SPORTIVO 1.8L PETROL" }, "body": { "type": [ "string", "null" ], "description": "Body type (SEDAN, HATCHBACK, UTE, SUV, etc.)", "example": "HATCHBACK" }, "engine": { "type": [ "string", "null" ], "description": "Engine displacement", "example": "1.8L" }, "vehicle_id": { "type": [ "integer", "null" ], "description": "PlateAPI ID of this exact vehicle variant. Stable: the same variant always has the same ID, here and in the vehicle database (/api/v1/vehicles). Null when the variant could not be identified with certainty; an ID is never guessed. With match multiple it identifies the first candidate, not necessarily the plate's own trim. Lookup text (make, model, description) can be worded differently from the record this ID points to; integrate on the ID, not the text.", "example": 5152708 }, "detailed_description": { "type": [ "string", "null" ], "description": "Extended vehicle description including chassis codes, drivetrain, fuel type, engine code, and power output. Only present when detailed=true is passed. May be null for some vehicles.", "example": "TOYOTA HILUX SR Auto or Manual AN120 AN130 05/2015~12/2020 4 Door UTE 4x4 DIESEL 2.8 litre, 1GD-FTV I4 16v DOHC I/C Turbo DI {130kW}" } } }, "LookupResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "vehicle": { "oneOf": [ { "$ref": "#/components/schemas/Vehicle" }, { "type": "null" } ] }, "source": { "type": "string", "description": "Always \"plateapi\". Present on successful lookups.", "example": "plateapi" }, "request_id": { "type": "string", "description": "Unique request identifier, also sent as the X-Request-ID response header. Present on every lookup response, including not_found and the sandbox.", "example": "req_7f3a9c1b4e8d2f6a0c5e" }, "duration_ms": { "type": "number", "description": "Total lookup time in milliseconds" }, "alternatives": { "type": "array", "items": { "$ref": "#/components/schemas/Vehicle" }, "description": "Other possible vehicle matches (e.g. different engine variants). Each has its own vehicle_id." }, "match": { "type": "string", "enum": [ "exact", "multiple", "ambiguous" ], "description": "exact: one variant. multiple: several trims of one make and model, all on sale at the same time (vehicle is the first with its vehicle_id, the rest are in alternatives). ambiguous: the candidates are different makes or models, or were not all on sale at the same time (for example different generations), so vehicle has vehicle_id null and alternatives lists every candidate, including the one shown as vehicle, each with its ID. Present on successful lookups." }, "sandbox": { "type": "boolean", "description": "Present and true only on sandbox test plate (TEST123) responses" }, "code": { "type": "string", "description": "Machine-readable error code (present when success is false): not_found (HTTP 200, uses quota), internal_error (HTTP 200, not billed) or lookup_failed (HTTP 503, not billed)" }, "error": { "type": "string", "description": "Human-readable error message (present when success is false)" } } }, "VehicleRecordResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "vehicle": { "type": "object", "properties": { "vehicle_id": { "type": "integer" }, "vehicle_type": { "type": "string", "enum": [ "car", "motorcycle" ], "description": "Which cascade the vehicle belongs to." }, "make": { "type": "string" }, "model": { "type": "string" }, "year_range": { "type": [ "string", "null" ], "description": "Model year range, e.g. 2015-2020 or 2020-ON" }, "lowest_year": { "type": [ "integer", "null" ] }, "highest_year": { "type": [ "integer", "null" ], "description": "Null for models still in production" }, "years": { "type": "array", "items": { "type": "integer" }, "description": "Model years this variant is listed under in the vehicle database. Empty when detail is basic." }, "description": { "type": "string" }, "long_description": { "type": [ "string", "null" ] }, "series": { "type": [ "string", "null" ], "description": "Series/chassis code" }, "engine": { "type": [ "string", "null" ] }, "variant": { "type": [ "string", "null" ], "description": "Variant name (select_text in the cascade)" }, "body": { "type": [ "string", "null" ], "description": "Body style read from the variant name, e.g. SEDAN, UTE, SUV, WAGON, HATCHBACK, TRUCK, VAN, COUPE, CONVERTIBLE, BUS. Null when the name does not carry it." }, "body_size": { "type": [ "string", "null" ], "description": "For SUVs: COMPACT, MEDIUM or FULL-SIZE." }, "doors": { "type": [ "integer", "null" ], "description": "Door count read from the variant name." }, "drive": { "type": [ "string", "null" ], "description": "4WD, AWD, RWD, FWD, or a wheels-x-driven configuration such as 4X2, 4X4, 6X4, 8X2 or 10X6, read from the variant name." }, "transmission": { "type": [ "string", "null" ], "description": "AT, MT, AT/MT, CVT, DCT or AMT, read from the variant name." }, "detail": { "type": "string", "enum": [ "full", "basic" ], "description": "full: complete record. basic: the vehicle has an ID but its full record has not been added yet; series, variant and long_description are null. The ID does not change when the full record is added." } } }, "duration_ms": { "type": "number" } } }, "VehiclesResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "make", "model", "year", "series", "engine", "variant", "vehicle" ] }, "data": { "type": "array" } } } }, "total": { "type": "integer", "description": "Number of results" }, "duration_ms": { "type": "number" } } } } }, "externalDocs": { "description": "Full API documentation", "url": "https://plateapi.com.au/docs/" } }