API REST
API de datos técnicos de vehículos por matrícula y bastidor
La API de APIVehículo devuelve, en una sola petición GET, más de 40 datos técnicos de un vehículo a partir de su matrícula (España y Portugal) o de su número de bastidor (VIN) con cobertura mundial. Autenticación con Bearer token, respuestas JSON consistentes y códigos HTTP estándar.
Actualizado el
Resumen
| Concepto | Valor |
|---|---|
| Base URL | https://api.apivehiculo.com/v1 |
| Endpoint de consulta | GET /vehicles/lookup |
| Autenticación | Authorization: Bearer av_… |
| Formato | JSON |
| Países (matrícula) | España (ES) y Portugal (PT) |
| Cobertura (VIN) | Mundial |
| Coste por consulta | 1 consulta del plan por respuesta 200; los errores no consumen |
Autenticación
Crea una cuenta, genera tu API key en el dashboard (prefijo av_) y envíala en la cabecera Authorization de cada petición. Puedes crear y revocar varias claves.
Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxMantén tu clave en secreto
Parámetros de GET /vehicles/lookup
Indica uno de los dos parámetros de búsqueda, plate o vin, nunca ambos.
| Parámetro | Tipo | Descripción |
|---|---|---|
plate | string | Matrícula sin espacios ni guiones, p. ej. 1234ABC. Incompatible con vin. |
vin | string | Número de bastidor de 17 caracteres. Incompatible con plate. |
country | string | Código ISO 3166-1 alpha-2 de la matrícula: ES (por defecto) o PT. No es necesario al buscar por VIN. |
Ejemplos de código
cURL
curl -H "Authorization: Bearer $APIVEHICULO_KEY" \
"https://api.apivehiculo.com/v1/vehicles/lookup?plate=1234ABC&country=ES"curl -H "Authorization: Bearer $APIVEHICULO_KEY" \
"https://api.apivehiculo.com/v1/vehicles/lookup?vin=WVWZZZ1KZAM123456"Node.js
const params = new URLSearchParams({ plate: '1234ABC', country: 'ES' });
const res = await fetch(`https://api.apivehiculo.com/v1/vehicles/lookup?${params}`, {
headers: { Authorization: `Bearer ${process.env.APIVEHICULO_KEY}` },
});
if (!res.ok) throw new Error(`APIVehículo ${res.status}`);
const { data } = await res.json();
console.log(data.brand, data.model, data.version);Python
import os, requests
res = requests.get(
"https://api.apivehiculo.com/v1/vehicles/lookup",
params={"plate": "1234ABC", "country": "ES"},
headers={"Authorization": f"Bearer {os.environ['APIVEHICULO_KEY']}"},
timeout=10,
)
res.raise_for_status()
vehicle = res.json()["data"]
print(vehicle["brand"], vehicle["model"], vehicle["engineCode"])PHP
$ch = curl_init("https://api.apivehiculo.com/v1/vehicles/lookup?" . http_build_query(["plate" => "1234ABC", "country" => "ES"]));
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("APIVEHICULO_KEY")],
]);
$vehicle = json_decode(curl_exec($ch), true)["data"];
curl_close($ch);
echo $vehicle["brand"] . " " . $vehicle["model"];Respuesta
Una respuesta correcta devuelve 200 con los datos del vehículo en data. El diccionario de campos describe cada uno.
{
"code": 200,
"message": "Vehicle found",
"data": {
"plate": "1234ABC",
"country": "ES",
"brand": "Volkswagen",
"model": "Golf",
"version": "2.0 TDI 150 CV",
"vin": "WVWZZZ1KZAM123456",
"firstRegistrationDate": "2018-03-15",
"fuelType": "Diesel",
"powerKW": "110",
"powerHP": "150",
"displacementCcm": "1968 CM3",
"engineCode": "CRBC",
"gearboxType": "Manual",
"bodyType": "Hatchback (3 or 5 doors)",
"co2": "119",
"tires": [
{ "name": "Front", "width": 205, "height": 55, "diameter": 16, "loadIndex": 91, "speedIndex": "V" }
]
// … más de 40 campos
}
}Códigos de error
Los errores devuelven siempre un objeto con message y status.
| Código | Significado | Ejemplo de mensaje |
|---|---|---|
| 400 | Parámetros incorrectos o faltantes | "Indica matrícula o vin, no ambos" |
| 401 | API key inválida o ausente | "Authentication token missing" |
| 404 | Vehículo no encontrado | "Vehicle not found" |
| 429 | Límite de consultas del plan alcanzado | "Has alcanzado el límite de búsquedas de este periodo" |
| 500 | Error interno del servidor | — |
Otros endpoints
GET /users/me: perfil del usuario asociado a la API key.GET /users/me/stats: consultas realizadas en la última hora, hoy, ayer, 30 días, 90 días y total.GET /subscriptions/me: plan activo, consultas usadas y restantes, y fechas del periodo.
La especificación OpenAPI 3 completa está disponible en https://api.apivehiculo.com/v1/docs/spec y, con ejemplos interactivos, en la sección de documentación del dashboard.
Preguntas frecuentes
¿Existe una API para consultar vehículos por matrícula en España?
Sí. APIVehículo ofrece una API REST con el endpoint GET https://api.apivehiculo.com/v1/vehicles/lookup que devuelve los datos técnicos de un vehículo a partir de su matrícula española (country=ES) o portuguesa (country=PT), o de su número de bastidor (vin).
¿Cómo me autentico en la API?
Con una API key con prefijo av_ que generas en el dashboard. Se envía en la cabecera Authorization: Bearer av_xxx en cada petición.
¿Se cobran las consultas que no encuentran el vehículo?
No. Sólo se descuenta una consulta de tu plan por cada petición con respuesta correcta (200). Las respuestas 400, 401, 404 y 429 no consumen consultas.
¿Qué ocurre si agoto las consultas de mi plan?
La API responde con 429. Puedes comprar consultas adicionales desde el dashboard sin cambiar de plan; se suman al periodo en curso.
¿Puedo cancelar mi plan en cualquier momento?
Sí, sin permanencia ni penalizaciones. Puedes cancelar tu suscripción cuando quieras desde el dashboard y seguirás disfrutando de tu plan, con tu API key activa y las consultas restantes, hasta el final del periodo ya abonado. A partir de ese momento no se realizará ningún cargo adicional.
¿Puedo usar la API desde el frontend de mi web o app?
No debes exponer tu API key en código del lado del cliente. Haz las llamadas desde tu backend y devuelve a tu frontend sólo los datos que necesites.