Vehicles

The Vehicles section provides access to detailed vehicle data within your account. This includes retrieving vehicle lists, specific vehicle details, and mileage statistics. The updated endpoints provide enhanced functionality, including support for pagination and the newly added ManifoldDetails property for deeper insights into vehicle specifications.

List Vehicles

Endpoint: GET /vehicles

Description:

Retrieve a list of all vehicles in your account. The response includes key details like vehicle ID, VIN, status, mileage, last known location, and additional specifications provided by the new ManifoldDetails property. Use optional pagination parameters to handle large datasets efficiently.

Headers:

Query Parameters:

Response:

{
  "status": 200,
  "message": "Success",
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "connectionId": "456e1234-e89b-12d3-a456-426614174111",
      "vin": "1HGCM82633A123456",
      "name": "Vehicle A",
      "status": "active",
      "mileage": 120000,
      "lastLocation": {
        "latitude": 37.7749,
        "longitude": -122.4194,
        "altitude": 15.5,
        "speed": 60,
        "timestamp": "2024-10-10T12:00:00Z"
      },
      "manifoldDetails": {
        "name": "HONDA Civic",
        "make": "HONDA",
        "company": "HONDA OF CANADA MFG., A DIVISION OF HONDA CANADA INC.",
        "model": "Civic",
        "constructionYear": 2013,
        "fuelType": "Gasoline",
        "bodyClass": "Sedan/Saloon",
				"type": "PASSENGER CAR"
      }
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 5,
    "pageSize": 10,
    "totalItems": 50
  }
}

Response Fields Explained:

• Main Fields:
  • id: Unique identifier for the vehicle.
  • connectionId: ID of the connection to which the vehicle belongs.
  • vin: Vehicle Identification Number.
  • name: Optional, human-readable name for easy reference.
  • status: Current status of the vehicle (e.g., active or inactive).
  • mileage: Total mileage recorded for the vehicle.
  • Last Location (Nested):
    • latitude: Latitude coordinate of the vehicle's last known location.
    • longitude: Longitude coordinate of the vehicle's last known location.
    • altitude: Altitude at the last known location (in meters).
    • speed: Speed of the vehicle at the last known location (in km/h).
    • timestamp: Time when the location was recorded (in ISO 8601 format).
  • Manifold Details:
    • name: Name of the vehicle.
    • make: Make of the vehicle.
    • company: Manufacturer of the vehicle.
    • model: Vehicle model name.
    • constructionYear: Year the vehicle was manufactured.
    • fuelType: Type of fuel the vehicle uses (e.g., Gasoline, Diesel, Electric).
    • bodyClass: Classification of the vehicle body (e.g., Sedan, Truck).
    • type: Type of the vehicle (e.g. BUS, INCOMPLETE VEHICLE).
• Pagination Metadata:
  • currentPage: The current page of the dataset being retrieved.
  • totalPages: Total number of pages available.
  • pageSize: Number of items per page.
  • totalItems: Total number of vehicles available.

Get Vehicle Details

Endpoint: GET /vehicles/{vehicleId}

Description:

Retrieve detailed information for a specific vehicle, identified by its unique vehicleId. The response includes key details such as VIN, status, mileage, last known location, and additional specifications provided by the ManifoldDetails property.

Path Parameters:

Headers:

Response:

{
  "status": 200,
  "message": "Success",
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "connectionId": "456e1234-e89b-12d3-a456-426614174111",
    "vin": "1HGCM82633A123456",
    "name": "Vehicle A",
    "status": "active",
    "mileage": 120000,
    "lastLocation": {
      "latitude": 37.7749,
      "longitude": -122.4194,
      "altitude": 15.5,
      "speed": 60,
      "timestamp": "2024-10-10T12:00:00Z"
    },
      "manifoldDetails": {
        "name": "HONDA Civic",
        "make": "HONDA",
        "company": "HONDA OF CANADA MFG., A DIVISION OF HONDA CANADA INC.",
        "model": "Civic",
        "constructionYear": 2013,
        "fuelType": "Gasoline",
        "bodyClass": "Sedan/Saloon",
				"type": "PASSENGER CAR"
      }
  }
}

Response Fields Explained:

Same as the fields explained in the List Vehicles endpoint.

Historical Vehicle Distance Driven

Endpoint: GET /vehicles/{vehicleId}/distance-driven

Description:

Retrieve historical distance data for a specific vehicle, allowing you to analyze the mileage covered over a specified time range.

Path Parameters:

Query Parameters:

Headers:

Response:

{
  "status": 200,
  "message": "Success",
  "data": {
    "distance": 150.5,
    "time": "2024-10-13T15:28:33.692Z"
  }
}

Response Fields Explained:

• distance: Total distance driven by the vehicle during the specified period (in kilometers).
• time: Timestamp for the distance data in ISO 8601 format.

Example Requests Using cURL

List Vehicles

curl --request GET \
  --url https://api.analytics.autos/vehicles \
  --header 'x-api-key: YOUR-API-KEY' \
  --header 'Connection-Id: YOUR-CONNECTION-ID'

Get Vehicle Details

curl --request GET \
  --url https://api.analytics.autos/vehicles/{vehicleId} \
  --header 'x-api-key: YOUR-API-KEY' \
  --header 'Connection-Id: YOUR-CONNECTION-ID'

Historical Vehicle Distance Driven

curl --request GET \
  --url https://api.analytics.autos/vehicles/{vehicleId}/distance-driven?from=2024-01-01T00:00:00Z&to=2024-01-31T23:59:59Z \
  --header 'x-api-key: YOUR-API-KEY' \
  --header 'Connection-Id: YOUR-CONNECTION-ID'

Get Vehicle Price by VIN

GET /vehicles/pricing

Returns current market pricing for a vehicle identified by its VIN. This includes used market data sourced from active listings across North America, and new/MSRP pricing where available. Results are cached for 90 days.

This endpoint is useful for underwriting workflows, total loss valuation, and fleet asset management. It does not require a fleet connection and can be called independently for any supported VIN.

Authentication: X-API-KEY header required.

Connection-Id: Not required for this endpoint.

Parameters

Rate Limiting

This endpoint has a stricter rate limit than most: 100 requests per day per API key. This limit is configurable per key. If you expect higher volume (for example, batch VIN lookups during underwriting), contact your account team.

A 429 response means you have hit this daily limit, not the general API rate limit.

Request Example

curl --request GET \
  --url "https://api.analytics.autos/vehicles/pricing?vin=1HGCM82633A123456" \
  --header "x-api-key: YOUR-API-KEY"

Response Fields

Top-level

vehicleInfo object

usedPrice object

newPrice object

Same structure as usedPrice. Returns null if the model year is no longer offered as new. A low priceCount here is expected for older or less common models.

Example Response

{
  "status": 200,
  "message": null,
  "data": {
    "vin": "1HGCM82633A123456",
    "vehicleInfo": {
      "make": "Honda",
      "model": "Accord",
      "year": "2003",
      "bodyClass": "Coupe",
      "fuelType": null,
      "vehicleType": null,
      "driveType": null,
      "manufacturer": "Honda"
    },
    "usedPrice": {
      "averagePrice": 4407.88,
      "minPrice": 480,
      "maxPrice": 12345,
      "medianPrice": 3544,
      "priceCount": 8,
      "lookedUpAt": "2026-03-16T19:16:46.3977752Z"
    },
    "newPrice": null,
    "location": "Ontario, Canada",
    "currency": "CAD",
    "source": "Multiple Canadian automotive marketplaces",
    "cached": false
  },
  "next": null
}

Notes and Edge Cases

• newPrice is null for vehicles whose model year is no longer sold new. This is expected behavior, not an error.
• Low priceCount values (such as 1 or 2) on usedPrice mean limited listings were found. Treat the pricing estimates with lower confidence in these cases.
• cached: true means the response was served from a prior lookup within the 90-day cache window. The lookedUpAt timestamp reflects when the data was originally fetched, not the current request time.
• location and currency reflect the market the pricing data was pulled from. Results are currently scoped to North America. Canadian listings return CAD; US listings return USD. The market is determined automatically based on listing availability for the VIN, not your account configuration.
• VIN format: The VIN must be exactly 17 characters and must not contain the letters I, O, or Q. Submitting an invalid VIN returns a 400 with a descriptive error.
• 504 responses indicate a timeout from the upstream pricing service. These are transient. Retry after a short delay. These do not count against your daily rate limit.
• This endpoint is independent of fleet connections. You do not need an active connection or a Connection-Id to call it.

Error Responses