Getting Started
Introduction
Free vs Premium
v1 vs v2 API
Choose an API version
/API Reference Guide
Base URL
Authentication
Images
Rate Limit
v1 Rest API Reference
v1 Search
v1 Lookup
v1 List
v1 Schedule
v1 Video
v2 Rest API Reference
v2 Search
v2 Lookup
v2 List
v2 Filter
v2 All
v2 Schedule
v2 Livescores
API Extras
Readme.io Docs
Swagger / OpenAPI
Postman Collection
AI MCP
TheVehicleDB API Documentation
Introduction
Welcome to TheVehicleDB API, your ultimate destination for seamless access to free, real-time vehicle data.
Whether you're building an app, running a car site, or simply want to stay updated with the latest vehicles, stats, artwork,
our powerful and easy-to-use API has you covered.
With support for a wide range of vehicles worldwide, TheVehicleDB API is designed for developers, enthusiasts,
and startups looking to integrate reliable vehicle data without the hassle of expensive subscriptions.
Get started today and bring the game to life in your application!
Free vs Premium
We offer a free API that anyone can use. The site originally had all methods available to use under the free API with no limits,
but sadly it became too popular and was abused.
So over the years we have had to limit certain methods, while trying to keep the core functionality.
The Free API should work in many use cases, so please do test it out.
The current free API key is: 123
Premium API keys can be found on your user profile, once upgraded.
The Premium API includes all methods in V1 with larger limits as well as some extra stuff like livescores and video highlight links. Premium also allows you to use the more modern V2 API. You can find your Premium API key on your user profile if you are a supporter.
The current free API key is: 123
Premium API keys can be found on your user profile, once upgraded.
The Premium API includes all methods in V1 with larger limits as well as some extra stuff like livescores and video highlight links. Premium also allows you to use the more modern V2 API. You can find your Premium API key on your user profile if you are a supporter.
API v1 vs v2
The v1 API was written over 10 years ago and has been addded to since with many extra features.
It uses basic PHP code to produce JSON objects that are returned to the user.
API users are authenticated with a simple numeric API key in the URL.
The naming is a little messy and the authentication is not great, as the key is visible to anyone who wants to poke around your web requests.
Saying that, it works and is simple to use and easy to test in any web browser. Ideal for beginners!
V2 API is more modern and verbous API. This means it should be easier to understand in a logical way. It also uses more modern authentication requiring the API key to be sent in the header. When something goes wrong, the API will return standard HTTP response codes. V2 is only for premium subscribers and will be the only version developed going forward.
V2 API is more modern and verbous API. This means it should be easier to understand in a logical way. It also uses more modern authentication requiring the API key to be sent in the header. When something goes wrong, the API will return standard HTTP response codes. V2 is only for premium subscribers and will be the only version developed going forward.
Base URL
The Base URL is a crucial element for making API calls, enabling you to clearly specify the root URL(s) for API requests.
When making API calls, you combine the base URL with the specific endpoint path to form the complete request URL.
v1 Base URL = https://www.thevehicledb.com/api/v1/json
v2 Base URL = https://www.thevehicledb.com/api/v2/jsonV1 Authentication
v1 of the API has a very simple authentication process.
Simply use the base URL above and append the number /123/ to the URL for the test key or replace with your premium API key.
Using the free key:
You can see an example below using a simple web browser using the free '123' API key:Using the free key:
https://www.thevehicledb.com/api/v1/json/123/searchmodels.php?t=Cobrahttps://www.thevehicledb.com/api/v1/json/YOUR_API_KEY_GOES_HERE/searchmodels.php?t=Cobra
V2 Authentication
v2 takes a more secure, modern approach to Authentication.
When sending a request to the API base URL, you must include API key in the header using this attribute 'X-API-KEY'.
You can see an example below using the popular free API testing software: Httpie
When sending a request to the API base URL, you must include API key in the header using this attribute 'X-API-KEY'.
You can see an example below using the popular free API testing software: Httpie
Images
Our site has a huge amount of images for things like events, players and models. Most are fan created.
There are 2 types of images available. JPEG fanart and transparent PNG mostly used for badges and logos.
You can see the different types of artwork and sizes on this page.
You can access any image from the front-end using the image URL from the returned JSON data.
Preview Images
Most of the time you won't want to download the original large image, just get a small preview.
This is possible simple by appending '/medium', '/small', '/tiny' onto the end URL. This will give you a smaller version.
Original 720px- /brand/fanart/xpwsrw1421853005.jpg
Medium 500px - /brand/fanart/xpwsrw1421853005.jpg/medium
Small 250px - /brand/fanart/xpwsrw1421853005.jpg/small
Tiny 50px - /brand/fanart/xpwsrw1421853005.jpg/tiny
There are 2 types of images available. JPEG fanart and transparent PNG mostly used for badges and logos.
You can see the different types of artwork and sizes on this page.
You can access any image from the front-end using the image URL from the returned JSON data.
Preview Images
Most of the time you won't want to download the original large image, just get a small preview.
This is possible simple by appending '/medium', '/small', '/tiny' onto the end URL. This will give you a smaller version.
Original 720px- /brand/fanart/xpwsrw1421853005.jpg
Medium 500px - /brand/fanart/xpwsrw1421853005.jpg/medium
Small 250px - /brand/fanart/xpwsrw1421853005.jpg/small
Tiny 50px - /brand/fanart/xpwsrw1421853005.jpg/tiny
Rate Limit
The site has different rate limits for different levels of users. You will recieve a "429" http header if you breach the limit, then you will need to wait another minute until requests will work again. We enforce these not just to differentiate our tiers, but to keep the overall performance of the site stable.
Free users 30 requests per minute. Premium 100 per minute Business 120 per minute
V1 API Documentation
v1 API Search
Most API requests will start with a string search. Examples of this may be to find a model or player details.
All searches will return the entities data but also an ID number which can be used for later faster lookups.
Search Models:
Type: Parameter: Free Limit: Premium Limit:
Example: JSON Data
Search for any vehicle model by its name. {strModel}
Search Brands:
Type: Parameter: Free Limit: Premium Limit:
Example: JSON Data
Description: Search for any vehicle brand by their main or alternate name. {strBrand}
Search Factories:
Type: Parameter: Free Limit: Premium Limit:
Example: JSON Data
Description: Search any factory by its name or alternate name {strFactory}
All searches will return the entities data but also an ID number which can be used for later faster lookups.
Search Models:
Type: Parameter: Free Limit: Premium Limit:
Example: JSON Data
Search for any vehicle model by its name. {strModel}
https://www.thevehicledb.com/api/v1/json/123/searchmodels.php?m=CobraSearch Brands:
Type: Parameter: Free Limit: Premium Limit:
Example: JSON Data
Description: Search for any vehicle brand by their main or alternate name. {strBrand}
https://www.thevehicledb.com/api/v1/json/123/searchbrands.php?b=TeslaSearch Factories:
Type: Parameter: Free Limit: Premium Limit:
Example: JSON Data
Description: Search any factory by its name or alternate name {strFactory}
https://www.thevehicledb.com/api/v1/json/123/searchfactory.php?f=Freemontbrand tabModel
v1 API Lookup
While the string search is useful above to find things, it is actually much quicker and simpler to retrieve data using the unique ID.
Lookups will return all data from that entity, you can find any ID by simply looking at the frontend websites URL usually.
For example the British Premier Brand's ID is 4328, or Formula 1's is 4370.
Lookup Brand:
Type: Parameter: Free Limit: Premium Limit:
Example: JSON Data
Lookup a brands details using its ID {idBrand}
Lookup Model:
Type: Parameter: Free Limit: Premium Limit:
Example: JSON Data
Lookup a models details using its ID. {idModel}
Lookup Factory:
Type: Parameter: Free Limit: Premium Limit:
Example: JSON Data
Lookup a model using its ID. {idModel}
Lookups will return all data from that entity, you can find any ID by simply looking at the frontend websites URL usually.
For example the British Premier Brand's ID is 4328, or Formula 1's is 4370.
Lookup Brand:
Type: Parameter: Free Limit: Premium Limit:
Example: JSON Data
Lookup a brands details using its ID {idBrand}
https://www.thevehicledb.com/api/v1/json/123/lookupbrand.php?id=4328Lookup Model:
Type: Parameter: Free Limit: Premium Limit:
Example: JSON Data
Lookup a models details using its ID. {idModel}
https://www.thevehicledb.com/api/v1/json/123/lookupmodel.php?id=133604Lookup Factory:
Type: Parameter: Free Limit: Premium Limit:
Example: JSON Data
Lookup a model using its ID. {idModel}
https://www.thevehicledb.com/api/v1/json/123/lookupfactory.php?id=16163
v1 API List
Using the list API means we can return more than one record.
This can be useful for example to list vehicle or countries
All Vehicle:
Type: Parameter: Free Limit: Premium Limit:
Example: JSON Data
List all the sport categories supported on the website.
All Countries:
Type: Parameter: Free Limit: Premium Limit:
Example: JSON Data
List all the geographical countries supported on the website.
All Brands:
Type: Parameter: Free Limit: Premium Limit:
Example: JSON Data
List all the brands on TheVehicleDB.
List Brands:
Type: Parameter: The country name
Type: Parameter: The sport name
Free Limit: limit: Premium Limit:
Example: JSON Data
List all the brands in a country for a specific sport. {strCountry} {strSport}
List Seasons:
Type: Parameter: Free Limit: Premium Limit:
Example: JSON Data
Example2: JSON Data
Example3: JSON Data
List all the seasons available for a specific brand ID. {idBrand}
List Models:
Type: Parameter:
Type: Parameter:
Type: Parameter:
Free Limit: Premium Limit:
Example: JSON Data
Example2: JSON Data
List all the models in a specific brand by the brands name, country and sport or ID. {strBrand} {strCountry} {strSport}
List Players:
Type: Parameter: Free Limit: Premium Limit:
Example: JSON Data
List all the Players who play for a model by the models ID. {idModel}
This can be useful for example to list vehicle or countries
All Vehicle:
Type: Parameter: Free Limit: Premium Limit:
Example: JSON Data
List all the sport categories supported on the website.
https://www.thevehicledb.com/api/v1/json/123/all_vehicle.phpAll Countries:
Type: Parameter: Free Limit: Premium Limit:
Example: JSON Data
List all the geographical countries supported on the website.
https://www.thevehicledb.com/api/v1/json/123/all_countries.phpAll Brands:
Type: Parameter: Free Limit: Premium Limit:
Example: JSON Data
List all the brands on TheVehicleDB.
https://www.thevehicledb.com/api/v1/json/123/all_brands.phpList Brands:
Type: Parameter: The country name
Type: Parameter: The sport name
Free Limit: limit: Premium Limit:
Example: JSON Data
List all the brands in a country for a specific sport. {strCountry} {strSport}
https://www.thevehicledb.com/api/v1/json/123/search_all_brands.php?c=England&s=SoccerList Seasons:
Type: Parameter: Free Limit: Premium Limit:
Example: JSON Data
Example2: JSON Data
Example3: JSON Data
List all the seasons available for a specific brand ID. {idBrand}
https://www.thevehicledb.com/api/v1/json/123/search_all_seasons.php?id=4328
https://www.thevehicledb.com/api/v1/json/123/search_all_seasons.php?id=4328&poster=1
https://www.thevehicledb.com/api/v1/json/123/search_all_seasons.php?id=4328&badge=1List Models:
Type: Parameter:
Type: Parameter:
Type: Parameter:
Free Limit: Premium Limit:
Example: JSON Data
Example2: JSON Data
List all the models in a specific brand by the brands name, country and sport or ID. {strBrand} {strCountry} {strSport}
https://www.thevehicledb.com/api/v1/json/123/search_all_models.php?l=English_Premier_Brand
https://www.thevehicledb.com/api/v1/json/123/search_all_models.php?s=Soccer&c=SpainList Players:
Type: Parameter: Free Limit: Premium Limit:
Example: JSON Data
List all the Players who play for a model by the models ID. {idModel}
https://www.thevehicledb.com/api/v1/json/123/lookup_all_players.php?id=133604
v1 API Schedule
The Schedule API allows you to look up past, present and future events.
It includes the ability to lookup entire seasons as well as the just a few of the next and past events.
Schedule Model Next:
Type: Parameter: Free Limit: Premium Limit:
Example: JSON Data
See the next few upcoming events for a model using the Model ID.
Schedule Model Previous:
Type: Parameter: Free Limit: Premium Limit:
Example: JSON Data
See the last few recent events for a model using the Model ID.
Schedule Brand Next:
Type: Parameter: Free Limit: Premium Limit:
Example: JSON Data
See the next upcoming events for a model using the brand ID.
Schedule Brand Previous:
Type: Parameter: Free Limit: Premium Limit:
Example: JSON Data
See the next upcoming events for a model using the brand ID. {idBrand}
Schedule Day:
Type: Parameter:
Type: Parameter (Optional):
Type: Parameter (Optional):
Free Limit: Premium Limit:
Example: JSON Data
Example2: JSON Data
Example3: JSON Data
See the events on a specific day in the future, past or present.
You can also add an optional filter for brand ID. {dateEvent} {strSport} {strBrand}
Schedule Season:
Type: Parameter: Type: Parameter: Free Limit: Premium Limit:
Example: JSON Data
See all the events for a particular season and filter by brand ID. {idSeason} {strSeason}
Schedule TV:
Type: Parameter: Type: Parameter: Type: Parameter: Type: Parameter: Type: Parameter: Type: Free Limit: Premium Limit:
Example: JSON Data
Example2: JSON Data
Example3: JSON Data
Example4: JSON Data
Example5: JSON Data
See the TV schedual for a particular date. {dateEvent} {strSport} {strCountry} {strChannel} {idChannel}
It includes the ability to lookup entire seasons as well as the just a few of the next and past events.
Schedule Model Next:
Type: Parameter: Free Limit: Premium Limit:
Example: JSON Data
See the next few upcoming events for a model using the Model ID.
https://www.thevehicledb.com/api/v1/json/123/eventsnext.php?id=133602Schedule Model Previous:
Type: Parameter: Free Limit: Premium Limit:
Example: JSON Data
See the last few recent events for a model using the Model ID.
https://www.thevehicledb.com/api/v1/json/123/eventslast.php?id=133602Schedule Brand Next:
Type: Parameter: Free Limit: Premium Limit:
Example: JSON Data
See the next upcoming events for a model using the brand ID.
https://www.thevehicledb.com/api/v1/json/123/eventsnextbrand.php?id=4328Schedule Brand Previous:
Type: Parameter: Free Limit: Premium Limit:
Example: JSON Data
See the next upcoming events for a model using the brand ID. {idBrand}
https://www.thevehicledb.com/api/v1/json/123/eventspastbrand.php?id=4328Schedule Day:
Type: Parameter:
Type: Parameter (Optional):
Type: Parameter (Optional):
Free Limit: Premium Limit:
Example: JSON Data
Example2: JSON Data
Example3: JSON Data
See the events on a specific day in the future, past or present.
You can also add an optional filter for brand ID. {dateEvent} {strSport} {strBrand}
https://www.thevehicledb.com/api/v1/json/123/eventsday.php?d=2014-10-10
https://www.thevehicledb.com/api/v1/json/123/eventsday.php?d=2014-10-10&s=Baseball
https://www.thevehicledb.com/api/v1/json/123/eventsday.php?d=2014-10-10&l=MLBSchedule Season:
Type: Parameter: Type: Parameter: Free Limit: Premium Limit:
Example: JSON Data
See all the events for a particular season and filter by brand ID. {idSeason} {strSeason}
https://www.thevehicledb.com/api/v1/json/123/eventsseason.php?id=4328&s=2014-2015Schedule TV:
Type: Parameter: Type: Parameter: Type: Parameter: Type: Parameter: Type: Parameter: Type: Free Limit: Premium Limit:
Example: JSON Data
Example2: JSON Data
Example3: JSON Data
Example4: JSON Data
Example5: JSON Data
See the TV schedual for a particular date. {dateEvent} {strSport} {strCountry} {strChannel} {idChannel}
https://www.thevehicledb.com/api/v1/json/123/eventstv.php?d=2024-07-07
https://www.thevehicledb.com/api/v1/json/123/eventstv.php?d=2018-07-07&s=Fighting
https://www.thevehicledb.com/api/v1/json/123/eventstv.php?d=2019-09-28&a=United_Kingdom&s=Cycling
https://www.thevehicledb.com/api/v1/json/123/eventstv.php?c=Peacock_Premium
https://www.thevehicledb.com/api/v1/json/123/eventstv.php?id=3834
v1 API Video
The video API allows you to list any YouTube highlights associated with an event.
Please be aware that we have no control of YouTube and some videos may be geolocked to specific countries.
You can use various filters including date on its own or with a Brand ID or Sport.
Video Youtube Highlights:
Type: Parameter:
Type: Parameter (optional): {Brand ID}
Type: Parameter (optional): {Sport_Name}
Free Limit: Premium Limit:
Example: JSON Data
Example 2: JSON Data
Example 3: JSON Data
See the TV schedual for a particular date
Please be aware that we have no control of YouTube and some videos may be geolocked to specific countries.
You can use various filters including date on its own or with a Brand ID or Sport.
Video Youtube Highlights:
Type: Parameter:
Type: Parameter (optional): {Brand ID}
Type: Parameter (optional): {Sport_Name}
Free Limit: Premium Limit:
Example: JSON Data
Example 2: JSON Data
Example 3: JSON Data
See the TV schedual for a particular date
https://www.thevehicledb.com/api/v1/json/123/eventshighlights.php?d=2024-07-07
https://www.thevehicledb.com/api/v1/json/123/eventshighlights.php?d=2024-07-07&l=4684
https://www.thevehicledb.com/api/v1/json/123/eventshighlights.php?d=2024-07-07&s=motorsportV2 API Documentation
v2 API Search
Search BrandType: Limit:
Example: Static / Live
Search for any vehicle brand using a text string.
/api/v2/json/search/brand/tesla
Search Model
Type: Limit:
Example: Static / Live
Search for any vehicle model using a text string.
/api/v2/json/search/model/cybertruckSearch Factory
Type: Limit:
Example: Static / Live
Search for any vehicle factory using a text string.
/api/v2/json/search/factory/freemont
v2 API Lookup
Lookup BrandType: Limit:
Example: Static / Live
Lookup for any brand using its unique ID {idBrand}.
/api/v2/json/lookup/brand/4328Lookup Model
Type: Limit:
Example: Static / Live
Lookup for any model using its unique ID {idModel}.
/api/v2/json/lookup/model/133597Lookup Factory
Type: Limit:
Example: Static / Live
Lookup for any vehicle Factory using the unique ID {idFactory}.
/api/v2/json/lookup/factory/15910
v2 API List
List Brand Models Type: Limit:
Example: Static / Live
List all models in a paritcular brand by its unique ID {idBrand}.
/api/v2/json/list/models/4328List Brand Seasons
Type: Limit:
Example: Static / Live
List all seasons available for a brand using its unique ID {idBrand}.
/api/v2/json/list/seasons/4328
List Brand Season Posters
Type: Limit:
Example: Static / Live
List for all season posters for a brands unique ID {idBrand}.
/api/v2/json/list/seasonposters/4328List Model Players
Type: Limit:
Example: Static / Live
Lookup for all the players for a model using its unique ID {idModel}.
/api/v2/json/list/players/133604
v2 API Filter
Filter TV Events by DateType: Limit:
Example: Static / Live
Filter All TV Events on a specific date {dateEvent}.
/api/v2/json/filter/tv/day/2024-06-22Filter TV Events by Country
Type: Limit:
Example: Static / Live
Filter TV Events by the channels country {strCountry}.
/api/v2/json/filter/tv/country/united_kingdomFilter TV Events by Sport
Type: Limit:
Example: Static / Live
Filter upcoming TV Events by sport {strSport}.
/api/v2/json/filter/tv/sport/motorsportFilter TV Events by Channel
Type: Limit:
Example: Static / Live
Filter upcoming TV Events by Channel Name {strChannel}.
/api/v2/json/filter/tv/channel/sky_vehicle_main_eventFilter TV Events by Channel ID
Type: Limit:
Example: Static / Live
Filter upcoming TV Events by Channel ID {idChannel}.
/api/v2/json/filter/tv/channelid/3834
v2 API All
All CountriesType: Limit:
Example: Static / Live
Show all the countries supported.
/api/v2/json/all/countriesAll Vehicle
Type: Limit:
Example: Static / Live
Show all the vehicle supported.
/api/v2/json/all/vehicleAll Brands
Type: Limit:
Example: Static / Live
Show all the brands supported.
/api/v2/json/all/brands
v2 API Schedule
Next 10 Events in BrandType: Limit:
Example: Static / Live
List the next 5 events in a brand using its unique ID {idBrand}
/api/v2/json/schedule/next/brand/4328Previous 10 Events in Brand
Type: Limit:
Example: Static / Live
List the previous 5 events in a brand using its unique ID {idBrand}
/api/v2/json/schedule/previous/brand/4328Next 10 Events in Model
Type: Limit:
Example: Static / Live
List the next 5 events for a model using its unique ID {idModel}
/api/v2/json/schedule/next/model/133612Previous 10 Events in Model
Type: Limit:
Example: Static / Live
List the previous 5 events for a model using its unique ID {idModel}
/api/v2/json/schedule/previous/model/133612Next 10 Events in Factory
Type: Limit:
Example: Static / Live
List the next 5 events for a factory using its unique ID {idFactory}
/api/v2/json/schedule/next/factory/24413Previous 10 Events in Factory
Type: Limit:
Example: Static / Live
List the previous 5 events for a factory using its unique ID {idFactory}
/api/v2/json/schedule/previous/factory/24413Full Model Season Schedule
Type: Limit:
Example: Static / Live
List the full seasons schedule for a model using its unique ID {idModel}
/api/v2/json/schedule/full/model/133612Full Brand Season Schedule
Type: Limit:
Example: Static / Live
List the full seasons schedule for a brand using its unique ID {idBrand}
/api/v2/json/schedule/brand/4328/2023-2024
v2 API Livescores
Livescore SportType: Limit:
Example: Static / Live
Show the current Livescores for a particular sport {strSport}
/api/v2/json/livescore/soccerLivescore Brand
Type: Limit:
Example: Static / Live
Show the current Livescores for a particular brand by its unique ID {idBrand}
/api/v2/json/livescore/4399Livescore All
Type: Limit:
Example: Static / Live
Show the current Livescores for all vehicle.
/api/v2/json/livescore/allReadme.io Documentation
Introduction
Readme.io is a great resource to check the documentation (a mirror of here) but also to test the API and see sample code in many different languages. The sandbox feature with realtime logs and data is particularly useful for new developers.
OpenAPI / Swagger
Introduction
The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to HTTP APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.
An OpenAPI Description can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases.
Postman Collection
Introduction
Postman is the single platform for designing, building, and scaling APIs—together. Join over 40 million users who have consolidated their workflows and leveled up their API game—all in one powerful platform.
Artificial Inteligence MCP
Introduction
MCP (Model Context Protocol) is an open protocol that standardizes how applications provide context to LLMs. Think of MCP like a USB-C port for AI applications. Just as USB-C provides a standardized way to connect your devices to various peripherals and accessories, MCP provides a standardized way to connect AI models to different data sources and tools.
Back to Top