carsxe

README

🚗 CarsXE API (Go Package)

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:

   • Register here
   • Add a payment method to activate your subscription and get your API key.

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

Example:

marketvalue := client.MarketValue(map[string]string{"vin": "WBAFR7C57CC811956"})

---

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"})

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

• type Client
  • func New(apiKey string, opts ...Option) *Client
  • func (c *Client) Get(endpoint string, params map[string]string) map[string]any
  • func (c *Client) History(params map[string]string) map[string]any
  • func (c *Client) Images(params map[string]string) map[string]any
  • func (c *Client) InternationalVINDecoder(params map[string]string) map[string]any
  • func (c *Client) LienAndTheft(params map[string]string) map[string]any
  • func (c *Client) MarketValue(params map[string]string) map[string]any
  • func (c *Client) ObdCodesDecoder(params map[string]string) map[string]any
  • func (c *Client) PlateDecoder(params map[string]string) map[string]any
  • func (c *Client) PlateImageRecognition(imageURL string) map[string]any
  • func (c *Client) Recalls(params map[string]string) map[string]any
  • func (c *Client) Specs(params map[string]string) map[string]any
  • func (c *Client) VinOCR(imageURL string) map[string]any
  • func (c *Client) YearMakeModel(params map[string]string) map[string]any
• type Option
  • func WithBaseURL(u string) Option
  • func WithHTTPClient(h *http.Client) Option
  • func WithSource(src string) Option

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

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 (vin)

func (*Client) ObdCodesDecoder

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

ObdCodesDecoder => GET /obdcodesdecoder (code)

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) Specs

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

Specs => GET /specs (vin required; deepdata, disableIntVINDecoding 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?)

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").