# CarsXE Vehicle Data for Snowflake

Get started with the [CarsXE Snowflake Native App](https://app.snowflake.com/marketplace/listing/GZ2FQZRTA1H/carsxe-vehicle-data-from-carsxe) for comprehensive vehicle data access directly in your Snowflake environment.

## Features

- **Vehicle Data Endpoints** including VIN decoding, plate lookup, market value, history, images, recalls, Lien And Theft checks, and more
- **Streamlit UI** with guided setup and interactive endpoint testing
- **SQL Interface** for direct procedure calls in your queries and workflows
- **Secure API Key Storage** encrypted within your Snowflake account
- **Auto-Navigation** through setup steps for quick onboarding

## Prerequisites

- A Snowflake account with Native App installation permissions
- A CarsXE account with an active API key ([Sign up here](/register))
- The app only requires outbound access to `api.carsxe.com` and does not access any other external domains.

## Installation

1. **Install from Snowflake Marketplace**
   - Search for "CarsXE"
   - Select the "Vehicle Data from CarsXE"
   - Click "Get" and follow the installation prompts

2. **Open the App**
   - Navigate to the installed app in your Snowflake account
   - The setup wizard will launch automatically

3. **Complete Setup (3 Simple Steps)**

   The app guides you through each step:

   **Step 1: Connect External Access**
   - Click "Connect CarsXE EAI ↗"
   - Select or create an External Access Integration for `api.carsxe.com`

   **Step 2: Add Your API Key**
   - Enter your CarsXE API key
   - Click "Validate API key" to verify and save
   - **Note:** The API key is now stored securely using a bind variable in the `CORE.CONFIG` table to prevent SQL identifier issues.

   **Step 3: Start Using the APIs**
   - You're ready! Select an endpoint and make your first call

## Using the Streamlit UI

1. **Choose an Endpoint** from the dropdown menu (e.g., "Specs (VIN specs)")
2. **Enter Required Fields** (marked clearly in the form)
3. **Add Optional Parameters** if needed (expand "Optional parameters" section)
4. **Click "Call endpoint"** to get results

## Using SQL Directly

You can call the app fully through SQL, without using the UI, via:

<CodeGroup title="SQL Procedure">
```sql
CALL CORE.CALL_CARSXE_ENDPOINT(
  path   => '<API_PATH>',
  method => '<HTTP_METHOD>',
  params => '<JSON string of params>'
);
```
</CodeGroup>

**Parameters:**

- `path` – API endpoint path (e.g., `"/specs"`, `/v2/platedecoder`, `/v2/marketvalue`). For a complete list of available endpoints and their versions, see the [CarsXE API Documentation](/docs)
- `method` – `"GET"` or `"POST"` (most endpoints use GET; some endpoints like plate recognition and VIN OCR use POST. Check the [API Documentation](/docs) for endpoint-specific method requirements)
- `params` – JSON string with endpoint-specific parameters (do not include `key`; the app injects it automatically)

### SQL Examples

> **Important:** Before using these SQL examples, you must complete the setup steps in the Streamlit UI app, including configuring the External Access Integration (EAI) and adding your API key. See the [Installation](#installation) section above for details.

#### Validating API Key

<CodeGroup title="SQL">
```sql 
-- Validate your CarsXE API key 
CALL CORE.VALIDATE_CARSXE_API_KEY('your_api_key_here'); 
```
</CodeGroup>

#### Saving API Key

<CodeGroup title="SQL">
```sql 
-- Save CarsXE API key in the secure CORE.CONFIG table 
CALL CORE.SET_CARSXE_API_KEY('your_api_key_here'); 
```
</CodeGroup>

> **Note:** The API key storage now uses a bind variable internally to avoid SQL compilation errors with identifiers.

#### Specs by VIN

<CodeGroup title="SQL">
```sql
CALL CORE.CALL_CARSXE_ENDPOINT(
  '/specs',
  'GET',
  '{"vin":"WBAFR7C57CC811956"}'
);
```
</CodeGroup>

#### Plate Decoder

<CodeGroup title="SQL">
```sql
CALL CORE.CALL_CARSXE_ENDPOINT(
  '/v2/platedecoder',
  'GET',
  '{"plate":"7XER187","country":"US","state":"CA"}'
);
```
</CodeGroup>

#### Market Value

<CodeGroup title="SQL">
```sql
CALL CORE.CALL_CARSXE_ENDPOINT(
  '/v2/marketvalue',
  'GET',
  '{"vin":"WBAFR7C57CC811956"}'
);
```
</CodeGroup>

#### Images

<CodeGroup title="SQL">
```sql
CALL CORE.CALL_CARSXE_ENDPOINT(
  '/images',
  'GET',
  '{"make":"toyota","model":"tacoma","year":"2018", "color":"blue","format":"json"}'
);
```
</CodeGroup>

#### Plate Image Recognition (image URL)

<CodeGroup title="SQL">
```sql
CALL CORE.CALL_CARSXE_ENDPOINT(
  '/platerecognition',
  'POST',
  '{"upload_url":"https://imagedelivery.net/moyiiSImjJPI_EZVxNMBBw/f49aed53-d736-4370-f3f4-97418841c800/public"}'
);
```
</CodeGroup>

#### VIN OCR (image URL)

<CodeGroup title="SQL">
```sql
CALL CORE.CALL_CARSXE_ENDPOINT(
  '/v1/vinocr',
  'POST',
  '{"upload_url":"https://user-images.githubusercontent.com/5663423/30922082-64edb4fa-a3a8-11e7-873e-3fbcdce8ea3a.png"}'
);
```
</CodeGroup>

#### Lien And Theft Check

<CodeGroup title="SQL">
```sql
CALL CORE.CALL_CARSXE_ENDPOINT(
  '/v1/lien-theft',
  'GET',
  '{"vin":"2C3CDXFG1FH762860"}'
);
```
</CodeGroup>

Internally, each call automatically adds `key=<your API key>` in the request to CarsXE.

## Security & Governance

- The API key is stored securely in the `CORE.CONFIG` table using a bind variable to prevent SQL injection and identifier issues.
- All external HTTP calls run through a Snowflake External Access Integration approved for the app, which follows Snowflake governance policies.
- The app does not store, cache, or log CarsXE API responses outside the execution context of the request; it simply returns them to the caller (UI or SQL).

## Limitations

- No built-in caching: each call goes directly to CarsXE, which means latency and rate limits depend on your CarsXE plan and network conditions.
- The app does not modify or normalize CarsXE responses; it returns them as received (wrapped in JSON where necessary).

## Support

- For API behavior, data quality, pricing, or rate limit issues, contact CarsXE support via their official channels.
- For issues specific to this Snowflake Native App (installation errors, procedure failures, UI errors), use the contact information provided on the Snowflake Marketplace listing.