Installation Guide¶

This guide covers installation for different use cases: data consumption, API integration, and development.

For Data Consumers¶

Download Pre-Built Datasets¶

No installation required! Simply download the files:

1. Go to Releases
2. Download your preferred format:
3. vehicles.json (23 MB)
4. vehicles.db (18 MB)
5. vehicles.sql (25 MB)
6. vehicles.csv (15 MB)
7. vehicles.xml (28 MB)

Verify Downloads¶

Check file integrity with SHA256 checksums:

sha256sum -c vehicles.json.sha256

For API Consumers¶

No Installation Needed¶

The API is hosted and ready to use:

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

Test the connection:

curl https://api.open-ev-data.org/v1/health

Optional: API Client Libraries¶

pip install requests

[dependencies]
reqwest = { version = "0.12", features = ["json"] }
tokio = { version = "1", features = ["full"] }

For Contributors¶

Dataset Development¶

Prerequisites¶

• Git: Download
• Node.js: Version 18+ Download
• Text Editor: VS Code recommended Download

Installation Steps¶

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

Verify Installation¶

npm run validate

Expected output:

✓ Schema validation passed
✓ All vehicles valid
✓ Sources verified
Total vehicles: 1234

API Development¶

Prerequisites¶

• Git: Download
• Rust: Version 1.80+ Install
• Cargo: Included with Rust

Installation Steps¶

rustup install stable
rustup default stable

Clone and build:

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

Verify Installation¶

cargo test --all
cargo clippy

Expected output:

running 45 tests
test result: ok. 45 passed; 0 failed; 0 ignored

Documentation Development¶

Prerequisites¶

• Git: Download
• Python: Version 3.13+ Download
• Poetry: Install

Installation Steps¶

Install Poetry:

curl -sSL https://install.python-poetry.org | python3 -

Clone and install:

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

Verify Installation¶

poetry run mkdocs serve

Visit http://localhost:8000 to see the documentation.

Multi-Repository Workspace Setup¶

For contributors working across multiple repositories.

Step 1: Create Parent Directory¶

mkdir open-ev-data
cd open-ev-data

Step 2: Clone All Repositories¶

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

Step 3: Open Workspace¶

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

Or in Cursor:

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

Step 4: Install All Dependencies¶

In separate terminals:

cd open-ev-data-dataset && npm install

cd ../open-ev-data-api && cargo build

cd ../open-ev-data.github.io && poetry install

System Requirements¶

Minimum Requirements¶

Recommended Requirements¶

Platform-Specific Notes¶

Windows¶

Install Git Bash or WSL2 for better compatibility:

wsl --install

Use PowerShell for native Windows commands.

macOS¶

Install Xcode Command Line Tools:

xcode-select --install

Use Homebrew for package management:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Linux¶

Install build essentials:

sudo apt update
sudo apt install build-essential git curl

sudo dnf groupinstall "Development Tools"
sudo dnf install git curl

sudo pacman -S base-devel git curl

Docker Setup (Optional)¶

API Server¶

Pull the Docker image:

docker pull ghcr.io/open-ev-data/ev-server:latest

Run the server:

docker run -p 3000:3000 \
  -v $(pwd)/vehicles.db:/app/vehicles.db:ro \
  ghcr.io/open-ev-data/ev-server:latest

Documentation¶

Build and serve locally:

docker build -t openev-docs .
docker run -p 8000:8000 openev-docs

Troubleshooting¶

Node.js Installation Issues¶

Check version:

node --version
npm --version

If outdated, use nvm:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18
nvm use 18

Rust Installation Issues¶

Update Rust:

rustup update

Check version:

rustc --version
cargo --version

Poetry Installation Issues¶

Verify installation:

poetry --version

Update Poetry:

poetry self update

Permission Errors¶

On Linux/macOS, avoid using sudo with npm:

npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH

Next Steps¶

Get Help¶

• GitHub Issues
• Discussions
• Documentation Home