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 integrate the API into your application.

Choose Your Path

Best for: Data scientists, researchers, analysts

You can access the data in multiple formats:

  1. Direct Download (Simplest)
  2. Download pre-compiled datasets from GitHub Releases

  3. Available formats: JSON, CSV, SQLite, PostgreSQL, XML

  4. Clone the Repository 

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

  5. Browse the Data

  6. Explore the dataset repository structure
  7. Read the Schema Reference

Next Steps: Quick Start →

Best for: Developers building applications

The REST API provides programmatic access to all vehicle data:

Base URL: https://api.open-ev-data.org/v1

Example Request: 

curl https://api.open-ev-data.org/v1/vehicles/tesla/model_3/2024

Features:

  • Fast response times (<50ms globally)
  • RESTful design
  • OpenAPI documentation
  • Filter and search capabilities
  • Pagination support

Next Steps: API 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 →

Prerequisites

Choose based on your path:

No prerequisites! Just download the files.

Optional: - SQLite viewer for .db files - JSON viewer/editor - Spreadsheet software for CSV

  • HTTP client (curl, Postman, or your programming language's HTTP library)
  • API key (coming soon - currently open access)

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: - Python 3.13+ - Poetry

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 API Getting Started or Project Setup Guide for detailed development setup.

Quick Examples

Query the API

curl https://api.open-ev-data.org/v1/vehicles?make=tesla

import requests

response = requests.get('https://api.open-ev-data.org/v1/vehicles/tesla/model_3/2024')
vehicle = response.json()
print(f"Range: {vehicle['range']['rated'][0]['range_km']} km")

fetch('https://api.open-ev-data.org/v1/vehicles/tesla/model_3/2024')
  .then(response => response.json())
  .then(vehicle => {
    console.log(`Range: ${vehicle.range.rated[0].range_km} km`);
  });

Load SQLite Database

import sqlite3

conn = sqlite3.connect('vehicles.db')
cursor = conn.cursor()

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

use rusqlite::{Connection, Result};

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

    let mut stmt = conn.prepare("SELECT * FROM vehicles WHERE make_slug = ?")?;
    let vehicles = stmt.query_map(["tesla"], |row| {
        Ok(row.get::<_, String>(0)?)
    })?;

    Ok(())
}

Next Steps

Ready to dive deeper? Here are some recommended paths:

Get Help

Community

Join our community: