carsxe

package module
v1.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 9, 2026 License: MIT Imports: 8 Imported by: 0

README

🚗 CarsXE API (Go Package)

Go Reference

CarsXE is a powerful and developer-friendly API that gives you instant access to a wide range of vehicle data. From VIN decoding and market value estimation to vehicle history, images, OBD code explanations, and plate recognition, CarsXE provides everything you need to build automotive applications at scale.

🌐 Website: https://api.carsxe.com
📄 Docs: https://api.carsxe.com/docs
📦 All Products: https://api.carsxe.com/all-products

To get started with the CarsXE API, follow these steps:

  1. Sign up for a CarsXE account:

  2. Install the CarsXE Go package:

    Run this command in your terminal:

    go get -u github.com/carsxe/carsxe-go-package

  3. Import the CarsXE API into your code:

    import "github.com/carsxe/carsxe-go-package"

  4. Initialize the API with your API key:

    client := carsxe.New("YOUR_API_KEY")

  5. Use the various endpoint methods provided by the API to access the data you need.

Usage

package main

import (
	"fmt"

	"github.com/carsxe/carsxe-go-package"
)

func main() {
	client := carsxe.New("YOUR_API_KEY")
	vin := "WBAFR7C57CC811956"

	vehicle := client.Specs(map[string]string{"vin": vin})
	fmt.Println(vehicle["input"].(map[string]interface{})["vin"])
}

📚 Endpoints

The CarsXE API provides the following endpoint methods:

Specs – Decode VIN & get full vehicle specifications

Required:

  • vin

Optional:

  • deepdata
  • disableIntVINDecoding

Example:

vehicle := client.Specs(map[string]string{"vin": "WBAFR7C57CC811956"})
InternationalVINDecoder – Decode VIN with worldwide support

Required:

  • vin

Optional:

  • None

Example:

intvin := client.InternationalVINDecoder(map[string]string{"vin": "WF0MXXGBWM8R43240"})
PlateDecoder – Decode license plate info (plate, country)

Required:

  • plate
  • country (always required except for US, where it is optional and defaults to 'US')

Optional:

  • state (required for some countries, e.g. US, AU, CA)
  • district (required for Pakistan)

Note:

  • The state parameter is required only when applicable (for specific countries such as US, AU, CA, etc.).
  • For Pakistan (country='pk'), both state and district are required.

Example:

decodedPlate := client.PlateDecoder(map[string]string{"plate": "7XER187", "state": "CA", "country": "US"})
MarketValue – Estimate vehicle market value based on VIN

Required:

  • vin

Optional:

  • state — US state code for regional pricing (e.g. CA, TX)
  • mileage — current mileage to adjust the value
  • condition — vehicle condition: excellent | clean | average | rough

Example:

marketvalueDetailed := client.MarketValue(map[string]string{"vin": "WBAFR7C57CC811956", "state": "CA", "mileage": "45000", "condition": "clean"})
History – Retrieve vehicle history

Required:

  • vin

Optional:

  • None

Example:

history := client.History(map[string]string{"vin": "WBAFR7C57CC811956"})
Images – Fetch images by make, model, year, trim

Required:

  • make
  • model

Optional:

  • year
  • trim
  • color
  • transparent
  • angle
  • photoType
  • size
  • license

Example:

images := client.Images(map[string]string{"make": "BMW", "model": "X5", "year": "2019"})
Recalls – Get safety recall data for a VIN

Required:

  • vin

Optional:

  • None

Example:

recalls := client.Recalls(map[string]string{"vin": "1C4JJXR64PW696340"})
PlateImageRecognition – Read & decode plates from images

Required:

  • imageURL

Optional:

  • None

Example:

plateimg := client.PlateImageRecognition("https://api.carsxe.com/img/apis/plate_recognition.JPG")
VinOCR – Extract VINs from images using OCR

Required:

  • imageURL

Optional:

  • None

Example:

vinocr := client.VinOCR("https://api.carsxe.com/img/apis/plate_recognition.JPG")
YearMakeModel – Query vehicle by year, make, model and trim (optional)

Required:

  • year
  • make
  • model

Optional:

  • trim

Example:

yymm := client.YearMakeModel(map[string]string{"year": "2012", "make": "BMW", "model": "5 Series"})
ObdCodesDecoder – Decode OBD error/diagnostic codes

Required:

  • code

Optional:

  • None

Example:

obdcode := client.ObdCodesDecoder(map[string]string{"code": "P0115"})
LienAndTheft – Check lien and theft records by VIN

Required:

  • vin

Optional:

  • None

Example:

lienTheft := client.LienAndTheft(map[string]string{"vin": "2C3CDXFG1FH762860"})
RecallsYmm – Get safety recall data by year, make, and model

Required:

  • year
  • make
  • model

Optional:

  • None

Example:

recallsYmm := client.RecallsYmm(map[string]string{"year": "2026", "make": "toyota", "model": "corolla"})
SubmitRecallsBatch – Submit VINs for async bulk recall checking

POST JSON to /v1/recalls-batch/submit. Provide at least one of vins, csv, or csvUrl (they can be combined). Max 10,000 unique VINs.

Required (at least one):

  • vins — array of 17-character VIN strings
  • csv — inline CSV text
  • csvUrl — HTTPS URL to a CSV file

Optional:

  • webhookUrl — HTTPS URL notified when the batch finishes

Example:

batch := client.SubmitRecallsBatch(map[string]any{
	"vins": []string{"1HGBH41JXMN109186", "5YJSA1E26HF000001", "1C4JJXR64PW696340"},
})
RecallsBatchStatus – Poll a recall batch job

Required:

  • batchId

Optional:

  • None

Example:

status := client.RecallsBatchStatus(map[string]string{"batchId": "brb_mnablbn7_wvbaqv"})
RecallsBatchResults – Fetch completed recall batch results as JSON

Required:

  • batchId

Optional:

  • None

Example:

results := client.RecallsBatchResults(map[string]string{"batchId": "brb_mnablbn7_wvbaqv"})
RecallsBatchDownload – Download completed recall batch results as CSV

Required:

  • batchId

Optional:

  • None

CSV responses are returned as map[string]any{"csv": "<csv text>"}. JSON error bodies are decoded as usual.

Example:

download := client.RecallsBatchDownload(map[string]string{"batchId": "brb_mnablbn7_wvbaqv"})
YmmOptions – List years, makes, models, variants, or trims for dropdowns

Required:

  • None (no filters lists years)

Optional:

  • dimension — years | makes | models | trims | variants
  • year
  • make (required for dimension=models)
  • model (required for dimension=trims, and for dimension=variants unless both year and make are set)
  • trim — substring filter on trim/variant names

Example:

years := client.YmmOptions(map[string]string{})
makes := client.YmmOptions(map[string]string{"year": "2026"})
models := client.YmmOptions(map[string]string{"make": "Toyota"})
variants := client.YmmOptions(map[string]string{"year": "2026", "make": "Toyota", "model": "Tacoma"})
OwnershipVin – Look up registered owner(s) by VIN

Enterprise only. Billed per owner returned; a 404 with error: "no_data" is not billed.

Required:

  • vin

Optional:

  • include — comma-separated subset of demographics,emails,phones,vehicle_history

Example:

owners := client.OwnershipVin(map[string]string{"vin": "1FT8X3BT0BEA61538"})
OwnershipPerson – Resolve contact details by name and address

Enterprise only.

Required:

  • first_name
  • last_name
  • address — street address only
  • zip — 5-digit US ZIP, optionally ZIP+4

Optional:

  • include — comma-separated subset of demographics,emails,phones,vehicle_history

Example:

person := client.OwnershipPerson(map[string]string{
	"first_name": "John",
	"last_name":  "Sample",
	"address":    "123 Example St",
	"zip":        "90210",
})
OwnershipAddress – Find residents at a street address

Enterprise only.

Required:

  • address — street address only
  • zip — 5-digit US ZIP, optionally ZIP+4

Optional:

  • include — comma-separated subset of demographics,emails,phones,vehicle_history
  • variant — legacy alias; prefer include

Example:

residents := client.OwnershipAddress(map[string]string{"address": "123 Example St", "zip": "90210"})
OwnershipZip – Search people in a ZIP code with optional filters

Enterprise only. Paginated; each returned record is billed.

Required:

  • zip — exactly 5 digits

Optional:

  • gender — M or F
  • min_age
  • max_age
  • income — letter code or full label (e.g. F or $50,000-$59,999)
  • page — default 1
  • limit — default 15, max 100
  • include — comma-separated subset of demographics,emails,phones,vehicle_history
  • variant — legacy alias; prefer include

Example:

area := client.OwnershipZip(map[string]string{"zip": "90210", "gender": "f", "min_age": "45"})

Notes & Best Practices

  • Parameter requirements: Each endpoint requires specific parameters—see the Required/Optional fields above.
  • Return values: All responses are Go maps (map[string]any) for easy access and manipulation.
  • Error handling: The client currently panics on network or JSON decode errors. Consider wrapping calls with recover or modifying the client to return errors for production use.
  • More info: For advanced usage and full details, visit the official API documentation.

Overall

The CarsXE Go package provides a wide range of powerful, easy-to-use tools for accessing and integrating vehicle data into your applications and services. Whether you're a developer or a business owner, you can quickly get the information you need to take your projects to the next level—without hassle or inconvenience.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is a minimal CarsXE API client that works with simple key/value maps.

func New 

func New(apiKey string, opts ...Option) *Client

New creates a new CarsXE client.

func (*Client) Get 

func (c *Client) Get(endpoint string, params map[string]string) map[string]any

Get performs a generic GET request to any endpoint with query params.

func (*Client) History 

func (c *Client) History(params map[string]string) map[string]any

History => GET /history (vin)

func (*Client) Images 

func (c *Client) Images(params map[string]string) map[string]any

Images => GET /images (make, model, optional year, trim, color, etc.)

func (*Client) InternationalVINDecoder 

func (c *Client) InternationalVINDecoder(params map[string]string) map[string]any

InternationalVINDecoder => GET /v1/international-vin-decoder (vin)

func (*Client) LienAndTheft added in v1.0.4 

func (c *Client) LienAndTheft(params map[string]string) map[string]any

func (*Client) MarketValue 

func (c *Client) MarketValue(params map[string]string) map[string]any

MarketValue => GET /v2/marketvalue Required: vin Optional: state (US state code), mileage (numeric string), condition (excellent|clean|average|rough)

func (*Client) ObdCodesDecoder 

func (c *Client) ObdCodesDecoder(params map[string]string) map[string]any

ObdCodesDecoder => GET /obdcodesdecoder (code)

func (*Client) OwnershipAddress added in v1.4.0 

func (c *Client) OwnershipAddress(params map[string]string) map[string]any

OwnershipAddress => GET /v1/ownership/address (address, zip; include?, variant?)

func (*Client) OwnershipPerson added in v1.4.0 

func (c *Client) OwnershipPerson(params map[string]string) map[string]any

OwnershipPerson => GET /v1/ownership/person (first_name, last_name, address, zip; include?)

func (*Client) OwnershipVin added in v1.4.0 

func (c *Client) OwnershipVin(params map[string]string) map[string]any

OwnershipVin => GET /v1/ownership/vin (vin; include?)

func (*Client) OwnershipZip added in v1.4.0 

func (c *Client) OwnershipZip(params map[string]string) map[string]any

OwnershipZip => GET /v1/ownership/zip (zip; gender?, min_age?, max_age?, income?, page?, limit?, include?, variant?)

func (*Client) PlateDecoder 

func (c *Client) PlateDecoder(params map[string]string) map[string]any

PlateDecoder => GET /v2/platedecoder (plate, country, state?, district?)

func (*Client) PlateImageRecognition 

func (c *Client) PlateImageRecognition(imageURL string) map[string]any

PlateImageRecognition => POST /platerecognition with JSON {"image": "<url>"}

func (*Client) Recalls 

func (c *Client) Recalls(params map[string]string) map[string]any

Recalls => GET /v1/recalls (vin)

func (*Client) RecallsBatchDownload added in v1.4.0 

func (c *Client) RecallsBatchDownload(params map[string]string) map[string]any

RecallsBatchDownload => GET /v1/recalls-batch/download (batchId) Returns decoded JSON on error/JSON responses, or {"csv": "<text>"} for CSV.

func (*Client) RecallsBatchResults added in v1.4.0 

func (c *Client) RecallsBatchResults(params map[string]string) map[string]any

RecallsBatchResults => GET /v1/recalls-batch/results (batchId)

func (*Client) RecallsBatchStatus added in v1.4.0 

func (c *Client) RecallsBatchStatus(params map[string]string) map[string]any

RecallsBatchStatus => GET /v1/recalls-batch/status (batchId)

func (*Client) RecallsYmm added in v1.4.0 

func (c *Client) RecallsYmm(params map[string]string) map[string]any

RecallsYmm => GET /v1/recalls-ymm (year, make, model)

func (*Client) Specs 

func (c *Client) Specs(params map[string]string) map[string]any

Specs => GET /specs (vin required; deepdata, disableIntVINDecoding optional)

func (*Client) SubmitRecallsBatch added in v1.4.0 

func (c *Client) SubmitRecallsBatch(body any) map[string]any

SubmitRecallsBatch => POST /v1/recalls-batch/submit JSON body: vins ([]string) and/or csv and/or csvUrl; webhookUrl optional

func (*Client) VinOCR 

func (c *Client) VinOCR(imageURL string) map[string]any

VinOCR => POST /v1/vinocr with JSON {"image": "<url>"}

func (*Client) YearMakeModel 

func (c *Client) YearMakeModel(params map[string]string) map[string]any

YearMakeModel => GET /v1/ymm (year, make, model, trim?)

func (*Client) YmmOptions added in v1.4.0 

func (c *Client) YmmOptions(params map[string]string) map[string]any

YmmOptions => GET /v1/ymm-options (dimension?, year?, make?, model?, trim?)

type Option 

type Option func(*Client)

Option configures a Client instance.

func WithBaseURL 

func WithBaseURL(u string) Option

WithBaseURL overrides the default API base URL.

func WithHTTPClient 

func WithHTTPClient(h *http.Client) Option

WithHTTPClient allows providing a custom *http.Client.

func WithSource 

func WithSource(src string) Option

WithSource changes the default "source" query parameter (default: "go").

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.