Skip to content

Getting Started with OpenEV Data

Welcome! This guide will help you get started with OpenEV Data, whether you want to use the data, contribute to the project, or run the API locally.

Choose Your Path

Best for: Data scientists, researchers, analysts, developers

Access pre-compiled EV datasets directly from our GitHub Releases:

Download from: GitHub Releases

Available Formats:

Format Best For
CSV Spreadsheets, data analysis, pandas
JSON Web apps, JavaScript/TypeScript projects
SQLite Local queries, mobile apps, embedded databases
PostgreSQL Production databases, cloud deployments
XML Enterprise integrations, legacy systems

Simply download the format you need - no installation required!

Next Steps: Quick Start →

Best for: Projects needing custom vehicle data

Fork the repository to create and maintain your own vehicle database:

  1. Fork the Repository
  2. Go to open-ev-data-dataset

  3. Click the "Fork" button

  4. Clone Your Fork 

    git clone https://github.com/YOUR_USERNAME/open-ev-data-dataset.git
cd open-ev-data-dataset
npm install

  5. Add Your Custom Data

  6. Add vehicle JSON files to src/ following the Schema Reference

  7. Run validation: npm run validate

  8. Generate Your Dataset

  9. Use the ETL pipeline to generate output files
  10. Configure GitHub Actions for automated releases

Next Steps: Dataset Documentation →

Best for: EV enthusiasts, engineers, manufacturers

Help us maintain the most accurate EV database:

Ways to Contribute:

  1. Add Vehicle Data
  2. Submit specifications for new EVs

  3. Check the Dataset Documentation

  4. Correct Existing Data

  5. Report inaccuracies

  6. Provide reliable sources

  7. Improve Documentation

  8. Fix typos and clarify instructions

  9. Add examples and tutorials

  10. Develop Features

  11. Work on the API or ETL pipeline
  12. Check the API Documentation

Next Steps: Contributing Guide →

Quick Start: Using the Data

Download Your Preferred Format

  1. Go to GitHub Releases
  2. Download the latest release in your preferred format
  3. Start using the data immediately!

Example: Load SQLite Database

import sqlite3

# Download the SQLite file from releases first
conn = sqlite3.connect('OpenEV Data (SQLite).db')
cursor = conn.cursor()

# List all Tesla vehicles
cursor.execute("SELECT * FROM vehicles WHERE make_slug = 'tesla'")
vehicles = cursor.fetchall()

for vehicle in vehicles:
    print(vehicle)

use rusqlite::{Connection, Result};

fn main() -> Result<()> {
    let conn = Connection::open("OpenEV Data (SQLite).db")?;

    let mut stmt = conn.prepare(
        "SELECT make_slug, model_slug FROM vehicles WHERE make_slug = ?"
    )?;

    let vehicles = stmt.query_map(["tesla"], |row| {
        Ok((row.get::<_, String>(0)?, row.get::<_, String>(1)?))
    })?;

    for vehicle in vehicles {
        println!("{:?}", vehicle?);
    }

    Ok(())
}

Example: Load CSV Data

import pandas as pd

# Download the CSV file from releases first
df = pd.read_csv('OpenEV Data (CSV).csv')

# Filter Tesla vehicles
tesla_vehicles = df[df['make_slug'] == 'tesla']
print(tesla_vehicles[['model_name', 'variant_name', 'battery_capacity_kwh']])

import { parse } from 'csv-parse/sync';
import { readFileSync } from 'fs';

const csv = readFileSync('OpenEV Data (CSV).csv', 'utf-8');
const vehicles = parse(csv, { columns: true });

const teslaVehicles = vehicles.filter(v => v.make_slug === 'tesla');
console.log(teslaVehicles);

Example: Load JSON Data

import json

# Download the JSON file from releases first
with open('OpenEV Data (JSON).json') as f:
    vehicles = json.load(f)

# Filter Tesla vehicles
tesla = [v for v in vehicles if v['make_slug'] == 'tesla']
for vehicle in tesla:
    print(f"{vehicle['model_name']} - {vehicle['variant_name']}")

import vehicles from './OpenEV Data (JSON).json';

const teslaVehicles = vehicles.filter(v => v.make_slug === 'tesla');
teslaVehicles.forEach(v => {
    console.log(`${v.model_name} - ${v.variant_name}`);
});

Running the API Locally

[!NOTE] There is no public API hosted online. To use the API, you need to run it locally using Docker or build it from source.

Quick Start with Docker

The fastest way to run the API locally:

git clone https://github.com/open-ev-data/open-ev-data-dataset.git
cd open-ev-data-dataset
docker-compose up -d

This will:

  • Download the latest dataset SQLite database
  • Start the API server on http://localhost:8080

Access the API:

curl http://localhost:8080/api/v1/vehicles

Stop the stack:

docker-compose down

Build from Source

For API development:

git clone https://github.com/open-ev-data/open-ev-data-api.git
cd open-ev-data-api
cargo build
cargo run

See the API Documentation for more details.

Prerequisites

Choose based on your path:

No prerequisites! Just download the files from GitHub Releases.

Optional:

  • SQLite viewer for .db files (e.g., DB Browser for SQLite)
  • JSON viewer/editor
  • Spreadsheet software for CSV (Excel, LibreOffice Calc, Google Sheets)
  • PostgreSQL client for .sql files

Or for building from source:

For Dataset Contributors:

  • Git
  • Node.js 18+
  • Text editor (VS Code recommended)
  • Understanding of JSON

For API Developers:

  • Rust 1.80+
  • Cargo
  • Understanding of REST APIs

For Documentation:

Development Installation

git clone https://github.com/open-ev-data/open-ev-data-dataset.git
cd open-ev-data-dataset
npm install
npm run validate

git clone https://github.com/open-ev-data/open-ev-data-api.git
cd open-ev-data-api
cargo build
cargo test

git clone https://github.com/open-ev-data/open-ev-data.github.io.git
cd open-ev-data.github.io
poetry install
poetry run mkdocs serve

Multi-Repository Workspace

For contributors working across multiple repositories, we provide a pre-configured workspace:

mkdir open-ev-data
cd open-ev-data
git clone https://github.com/open-ev-data/open-ev-data-dataset.git
git clone https://github.com/open-ev-data/open-ev-data-api.git
git clone https://github.com/open-ev-data/open-ev-data.github.io.git
git clone https://github.com/open-ev-data/.github.git

Then open the workspace file:

code .github/open-ev-data.code-workspace

Benefits:

  • Unified search across all repositories
  • Cross-repository navigation
  • Consistent settings
  • Organized sidebar

See the Project Setup Guide for detailed development setup.

Next Steps

Ready to dive deeper? Here are some recommended paths:

Get Help

Community

Join our community: