1. Overview<\/h2>\n\n\n\n
The API provides four V1 endpoints:<\/p>\n\n\n\n Demo API:<\/strong> The Demo environment is intended for integration testing. A Demo API key is provided separately and is not published in this documentation.<\/p>\n\n\n\n All API requests require a Vehicle Database API key.<\/p>\n\n\n\n Send the key using the HTTP Keep API keys private.<\/strong> Do not commit keys to source control, publish them in documentation, place them in URLs, or expose production keys in browser-side JavaScript.<\/p>\n\n\n\n The recommended integration pattern is: <\/p>\n\n\n\n Best practice:<\/strong> Use the Years \u2192 Makes \u2192 Models \u2192 Search workflow rather than maintaining your own vehicle Make\/Model list or guessing vehicle combinations.<\/p>\n\n\n\n GET<\/strong>\/years<\/p>\n\n\n\n Returns all vehicle years currently available in the Vehicle Database.<\/p>\n\n\n\n GET<\/strong>\/makes?year={year}<\/p>\n\n\n\n Returns all Makes available for the selected Year.<\/p>\n\n\n\n GET<\/strong>\/models?year={year}&make={make}<\/p>\n\n\n\n Returns all Models available for the selected Year and Make.<\/p>\n\n\n\n The Make input is case-insensitive. For example, The API returns the canonical Make value maintained in the Vehicle Database.<\/p>\n\n\n\n GET<\/strong>\/search?year={year}&make={make}&model={model}<\/p>\n\n\n\n Returns vehicle specifications matching the supplied Year, Make, and Model.<\/p>\n\n\n\n The Search endpoint returns a maximum of 50 matching records per request.<\/p>\n\n\n\n All matching vehicle configurations are returned up to the endpoint limit. Years, Makes, and Models return a consistent structure:<\/p>\n\n\n\n Make\/Model lookup responses also include the selected Year and\/or canonical Make.<\/p>\n\n\n\n Search returns:<\/p>\n\n\n\n Wildcard characters are intentionally rejected. Examples:<\/p>\n\n\n\n Response:<\/p>\n\n\n\n The API supports case-insensitive input, but does not perform partial or wildcard matching. Use the progressive lookup endpoints to discover valid values.<\/p>\n\n\n\n A valid request that has no matching vehicle returns a successful response with an empty data array.<\/p>\n\n\n\n This is different from an invalid request or authentication failure.<\/p>\n\n\n\n Each API key has an independently configured requests-per-minute limit.<\/p>\n\n\n\n The standard production limit is currently 100 requests per minute<\/strong>, although limits may be configured differently for individual clients.<\/p>\n\n\n\n When the limit is exceeded, the API returns:<\/p>\n\n\n\n Applications should wait for the current rate-limit window to reset before retrying.<\/p>\n\n\n\n Browser applications:<\/strong> Do not expose a production API key in client-side JavaScript delivered to end users. If browser-side access is required, use your own server-side application as a secure proxy.<\/p>\n\n\n\n A Postman collection can be provided for clients who prefer an interactive testing environment.<\/p>\n\n\n\n The collection should use variables rather than embedding a real API key:<\/p>\n\n\n\n For Demo testing:<\/p>\n\n\n\n For Production:<\/p>\n\n\n\n The API key should be entered by the client into the Postman environment or collection variable.<\/p>\n\n\n\n The following capabilities are planned for future releases and are not currently part of V1.<\/p>\n\n\n\n This endpoint will allow clients to retrieve available engines for a selected Year, Make, and Model.<\/p>\n\n\n\n A future data-feed API will allow authorized clients to download vehicle data in bulk, potentially as a compressed ZIP package.<\/p>\n\n\n\n Important:<\/strong> Future endpoints are shown for roadmap purposes only and should not be used until they are officially released.<\/p>\n\n\n\n Production API access requires an issued Vehicle Database API key.<\/p>\n\n\n\n Demo API access is available for integration testing.Endpoint<\/th> Purpose<\/th><\/tr> GET \/years<\/code><\/td>Returns all available vehicle years.<\/td><\/tr> GET \/makes?year=<\/code><\/td>Returns all Makes available for a selected Year.<\/td><\/tr> GET \/models?year=&make=<\/code><\/td>Returns all Models available for a selected Year and Make.<\/td><\/tr> GET \/search?year=&make=&model=<\/code><\/td>Returns matching vehicle specifications.<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n 2. Base URLs<\/h2>\n\n\n\n
Production<\/h3>\n\n\n\n
https://mage-extensions-themes.com\/rest\/V1\/vehicleapi<\/code><\/pre>\n\n\n\nDemo<\/h3>\n\n\n\n
https://demo.mage-extensions-themes.com\/rest\/V1\/vehicleapi<\/code><\/pre>\n\n\n\n3. Authentication<\/h2>\n\n\n\n
Authorization<\/code> header:<\/p>\n\n\n\nAuthorization: Bearer vdb_live_xxxxxxxxxxxxxxxxxxxxxxxxx<\/code><\/pre>\n\n\n\ncURL Example<\/h3>\n\n\n\n
curl -i \\\n \"https:\/\/mage-extensions-themes.com\/rest\/V1\/vehicleapi\/years\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\"<\/code><\/pre>\n\n\n\n4. Recommended Integration Workflow<\/h2>\n\n\n\n
![\"\"](\"https:\/\/global-ecommerce-services.com\/wiki\/wp-content\/uploads\/2026\/08\/vapi-integration-diagram-361x1024.png\"){kind=spacer}
<\/figure>\n\n\n\n5. Get Available Years<\/h2>\n\n\n\n
Request<\/h3>\n\n\n\n
curl -i \\\n \"https:\/\/mage-extensions-themes.com\/rest\/V1\/vehicleapi\/years\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\"<\/code><\/pre>\n\n\n\nResponse<\/h3>\n\n\n\n
{\n \"success\": true,\n \"count\": 132,\n \"data\": [\n \"2027\",\n \"2026\",\n \"2025\",\n \"2024\",\n \"2023\"\n ]\n}<\/code><\/pre>\n\n\n\n6. Get Makes for a Year<\/h2>\n\n\n\n
Parameter<\/th> Required<\/th> Description<\/th><\/tr> year<\/code><\/td>Yes<\/td> Four-digit vehicle year.<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n Request<\/h3>\n\n\n\n
curl -i \\\n \"https:\/\/mage-extensions-themes.com\/rest\/V1\/vehicleapi\/makes?year=2027\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\"<\/code><\/pre>\n\n\n\nResponse<\/h3>\n\n\n\n
{\n \"success\": true,\n \"year\": \"2027\",\n \"count\": 63,\n \"data\": [\n \"Acura\",\n \"Audi\",\n \"BMW\",\n \"Ford\",\n \"Honda\",\n \"Toyota\",\n \"Volkswagen\",\n \"Volvo\"\n ]\n}<\/code><\/pre>\n\n\n\n7. Get Models for Year and Make<\/h2>\n\n\n\n
Parameter<\/th> Required<\/th> Description<\/th><\/tr> year<\/code><\/td>Yes<\/td> Four-digit vehicle year.<\/td><\/tr> make<\/code><\/td>Yes<\/td> Vehicle Make. Input is case-insensitive.<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n Request<\/h3>\n\n\n\n
curl -i \\\n \"https:\/\/mage-extensions-themes.com\/rest\/V1\/vehicleapi\/models?year=2025&make=Toyota\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\"<\/code><\/pre>\n\n\n\nResponse<\/h3>\n\n\n\n
{\n \"success\": true,\n \"year\": \"2025\",\n \"make\": \"Toyota\",\n \"count\": 26,\n \"data\": [\n \"4Runner\",\n \"Avanza\",\n \"bZ4X\",\n \"Camry\",\n \"Corolla\",\n \"Corolla Cross\",\n \"Crown\",\n \"Crown Signia\",\n \"GR Corolla\",\n \"GR Supra\",\n \"GR86\",\n \"Grand Highlander\",\n \"Hiace\",\n \"Highlander\",\n \"Hilux\",\n \"Land Cruiser\",\n \"Mirai\",\n \"Prius\",\n \"Raize\",\n \"RAV4\",\n \"Sequoia\",\n \"Sienna\",\n \"Supra\",\n \"Tacoma\",\n \"Tundra\",\n \"Yaris\"\n ]\n}<\/code><\/pre>\n\n\n\nCase-insensitive input<\/h3>\n\n\n\n
Toyota<\/code>, toyota<\/code>, and TOYOTA<\/code> identify the same Make.<\/p>\n\n\n\nRequest:\n?year=1985&make=bmw\n\nResponse:\n\"year\": \"1985\",\n\"make\": \"BMW\"<\/code><\/pre>\n\n\n\n8. Search Vehicle Specifications<\/h2>\n\n\n\n
Parameter<\/th> Required<\/th> Description<\/th><\/tr> year<\/code><\/td>Yes<\/td> Four-digit vehicle year.<\/td><\/tr> make<\/code><\/td>Yes<\/td> Vehicle Make.<\/td><\/tr> model<\/code><\/td>Yes<\/td> Vehicle Model.<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n Request<\/h3>\n\n\n\n
curl -i \\\n \"https:\/\/mage-extensions-themes.com\/rest\/V1\/vehicleapi\/search?make=Honda&model=Civic&year=2025\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\"<\/code><\/pre>\n\n\n\nResponse<\/h3>\n\n\n\n
{\n \"success\": true,\n \"count\": 11,\n \"has_more\": false,\n \"data\": [\n {\n \"ymm_id\": \"6072792945\",\n \"make\": \"Honda\",\n \"model\": \"Civic\",\n \"year\": \"2025\",\n \"engine\": \"2.0L 1993CC 122Cu. In. l4 GAS DOHC Naturally Aspirated\",\n \"submodel\": \"Sport\",\n \"trim\": \"Sport Hatchback 4-Door\",\n \"body\": \"Hatchback\",\n \"cylinder_type\": \"DOHC\",\n \"drive_type\": \"FWD\",\n \"engine_block_type\": \"L\",\n \"engine_cc\": \"1993\",\n \"engine_cid\": \"122\",\n \"engine_cylinders\": \"4\",\n \"engine_liter_display\": \"2.0L\",\n \"transmission\": \"Automatic\",\n \"fuel_type\": \"GAS\",\n \"vehicle_display_name\": \"Honda Civic 2025 Sport\",\n \"number_of_doors\": \"4\",\n \"aspiration\": \"Naturally Aspirated\",\n \"parts_model\": \"Civic\",\n \"market_region\": \"1|2\"\n }\n ]\n}<\/code><\/pre>\n\n\n\nhas_more<\/code> indicates whether additional matching records exist beyond the returned set.<\/p>\n\n\n\n9. Response Format<\/h2>\n\n\n\n
Lookup endpoints<\/h3>\n\n\n\n
{\n \"success\": true,\n \"count\": 0,\n \"data\": []\n}<\/code><\/pre>\n\n\n\nSearch endpoint<\/h3>\n\n\n\n
{\n \"success\": true,\n \"count\": 0,\n \"has_more\": false,\n \"data\": []\n}<\/code><\/pre>\n\n\n\n10. Input Rules<\/h2>\n\n\n\n
Wildcards are not supported<\/h3>\n\n\n\n
make=Toy%\nmake=Toy_\nmodel=Cam%<\/code><\/pre>\n\n\n\n{\n \"message\": \"Wildcard characters are not allowed.\"\n}<\/code><\/pre>\n\n\n\nExact lookup values<\/h3>\n\n\n\n
11. Empty Results<\/h2>\n\n\n\n
{\n \"success\": true,\n \"count\": 0,\n \"has_more\": false,\n \"data\": []\n}<\/code><\/pre>\n\n\n\n12. Error Responses<\/h2>\n\n\n\n
Condition<\/th> HTTP Status<\/th> Example<\/th><\/tr> Missing API key<\/td> 401<\/td> API key is required.<\/code><\/td><\/tr>Invalid API key<\/td> 401<\/td> Invalid API key.<\/code><\/td><\/tr>Missing required parameter<\/td> 400<\/td> Magento Web API required-field response<\/td><\/tr> Invalid Year<\/td> 400<\/td> Year must be a four-digit year.<\/code><\/td><\/tr>Wildcard characters<\/td> 400<\/td> Wildcard characters are not allowed.<\/code><\/td><\/tr>Rate limit exceeded<\/td> 429<\/td> Retry after the rate-limit window.<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n Example: Missing Make<\/h3>\n\n\n\n
{\n \"message\": \"\\\"%fieldName\\\" is required. Enter and try again.\",\n \"parameters\": {\n \"fieldName\": \"make\"\n }\n}<\/code><\/pre>\n\n\n\nExample: Invalid Year<\/h3>\n\n\n\n
{\n \"message\": \"Year must be a four-digit year.\"\n}<\/code><\/pre>\n\n\n\n13. Rate Limiting<\/h2>\n\n\n\n
Rate-limit headers<\/h3>\n\n\n\n
X-RateLimit-Limit: 100\nX-RateLimit-Remaining: 99<\/code><\/pre>\n\n\n\nHTTP 429 Too Many Requests<\/code><\/pre>\n\n\n\n14. cURL Examples<\/h2>\n\n\n\n
Get Years<\/h3>\n\n\n\n
curl -i \\\n \"https:\/\/mage-extensions-themes.com\/rest\/V1\/vehicleapi\/years\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\"<\/code><\/pre>\n\n\n\nGet Makes<\/h3>\n\n\n\n
curl -i \\\n \"https:\/\/mage-extensions-themes.com\/rest\/V1\/vehicleapi\/makes?year=2025\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\"<\/code><\/pre>\n\n\n\nGet Models<\/h3>\n\n\n\n
curl -i \\\n \"https:\/\/mage-extensions-themes.com\/rest\/V1\/vehicleapi\/models?year=2025&make=Toyota\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\"<\/code><\/pre>\n\n\n\nSearch<\/h3>\n\n\n\n
curl -i \\\n \"https:\/\/mage-extensions-themes.com\/rest\/V1\/vehicleapi\/search?year=2025&make=Honda&model=Civic\" \\\n -H \"Authorization: Bearer YOUR_API_KEY\"<\/code><\/pre>\n\n\n\n15. PHP Example<\/h2>\n\n\n\n
<?php\n\n$apiKey = 'YOUR_API_KEY';\n\n$url = 'https:\/\/mage-extensions-themes.com\/rest\/V1\/vehicleapi\/search'\n . '?year=2025'\n . '&make=Honda'\n . '&model=Civic';\n\n$ch = curl_init($url);\n\ncurl_setopt_array($ch, [\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer ' . $apiKey,\n 'Accept: application\/json',\n ],\n]);\n\n$response = curl_exec($ch);\n\nif ($response === false) {\n throw new RuntimeException(curl_error($ch));\n}\n\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\n\ncurl_close($ch);\n\n$data = json_decode($response, true);\n\nif ($httpCode !== 200) {\n throw new RuntimeException(\n $data['message'] ?? 'API request failed.'\n );\n}\n\nforeach ($data['data'] as $vehicle) {\n echo $vehicle['vehicle_display_name'] . PHP_EOL;\n}<\/code><\/pre>\n\n\n\n16. Python Example<\/h2>\n\n\n\n
import requests\n\napi_key = \"YOUR_API_KEY\"\n\nurl = \"https:\/\/mage-extensions-themes.com\/rest\/V1\/vehicleapi\/search\"\n\nparams = {\n \"year\": \"2025\",\n \"make\": \"Honda\",\n \"model\": \"Civic\"\n}\n\nheaders = {\n \"Authorization\": f\"Bearer {api_key}\",\n \"Accept\": \"application\/json\"\n}\n\nresponse = requests.get(\n url,\n params=params,\n headers=headers,\n timeout=30\n)\n\nresponse.raise_for_status()\n\ndata = response.json()\n\nfor vehicle in data[\"data\"]:\n print(vehicle[\"vehicle_display_name\"])<\/code><\/pre>\n\n\n\n17. JavaScript \/ Node.js Example<\/h2>\n\n\n\n
const response = await fetch(\n \"https:\/\/mage-extensions-themes.com\/rest\/V1\/vehicleapi\/search?year=2025&make=Honda&model=Civic\",\n {\n headers: {\n \"Authorization\": \"Bearer YOUR_API_KEY\",\n \"Accept\": \"application\/json\"\n }\n }\n);\n\nconst data = await response.json();\n\nconsole.log(data);<\/code><\/pre>\n\n\n\n18. Postman<\/h2>\n\n\n\n
VDB_BASE_URL\nVDB_API_KEY<\/code><\/pre>\n\n\n\nVDB_BASE_URL =\nhttps://demo.mage-extensions-themes.com\/rest\/V1\/vehicleapi<\/code><\/pre>\n\n\n\nVDB_BASE_URL =\nhttps://mage-extensions-themes.com\/rest\/V1\/vehicleapi<\/code><\/pre>\n\n\n\n19. Integration Best Practices<\/h2>\n\n\n\n
\n
X-RateLimit-Remaining<\/code> and avoid unnecessary requests.<\/li>\n\n\n\n20. Future API Features<\/h2>\n\n\n\n
Engine Lookup<\/h3>\n\n\n\n
GET \/engines?year={year}&make={make}&model={model}<\/code><\/pre>\n\n\n\nBulk Data Feed<\/h3>\n\n\n\n
21. API Access and Support<\/h2>\n\n\n\n
Contact Global eCom to request a Demo API key. <\/p>\n\n\n\n