API Documentation

Getting Started

Welcome to MatrixAPI - your source for comprehensive, immutable reference data. Our APIs provide high-performance, cacheable data including vehicles, countries, geographic subdivisions, and more.

Base URL

https://matrixapi.dev/api/v1/

Quick Start

# Get minimal vehicle data (perfect for dropdowns)
curl https://matrixapi.dev/api/v1/vehicles

# Get comprehensive vehicle data  
curl https://matrixapi.dev/api/v1/vehicles?all=true

# Get specific vehicle models
curl https://matrixapi.dev/api/v1/vehicles/2025/tesla

Authentication

MatrixAPI is currently publicly accessible and does not require authentication. All endpoints can be accessed directly without API keys.

Free & Open: No authentication required - all endpoints are public and free to use.

Response Patterns

All MatrixAPI endpoints follow a consistent, developer-friendly pattern optimized for both dropdown/UI components and comprehensive data access.

Two Response Modes

πŸ“‹ Minimal (Default)

Perfect for dropdowns, forms, and UI components

{
  "vehicles": [
    {
      "name": "Tesla",
      "endpoint": "/api/v1/vehicles/2025/tesla"
    }
  ],
  "total": 99,
  "statistics": {...}
}

πŸ“Š Comprehensive (?all=true)

Complete data with all available fields

{
  "vehicles": [
    {
      "name": "Tesla",
      "full_name": "TESLA, INC.",
      "country": "UNITED STATES (USA)",
      "vehicle_types": ["Passenger Car"],
      "total_models": 15,
      "endpoint": "/api/v1/vehicles/2025/tesla"
    }
  ]
}

Standard Response Structure

{
  "[resource_name]": [...],           // Main data array
  "total": 249,                       // Count of items
  "statistics": {...},                // Performance metrics
  "available_[filters]": [...],       // Available filter options
  "cache_duration": "immutable",      // Cache information
  "examples": {...},                  // Usage examples
  "endpoints": {...},                 // Related endpoints
  "available_fields": [...],          // Current response fields
  "query_parameters": {...}           // Parameter descriptions
}

πŸš— Vehicles API

GET /vehicles

All vehicle makes index

GET /vehicles/{make}

Current year models for make

GET /vehicles/{year}/{make}

Specific year models

Query Parameters

  • country - Filter by manufacturer country (e.g., 'UNITED STATES (USA)', 'GERMANY')
  • type - Filter by vehicle type (car, mpv, truck, motorcycle, all) - supports comma-separated
  • all - Set to 'true' to include comprehensive data fields

Examples

# Minimal data for dropdowns
GET /api/v1/vehicles
# Filter by country
GET /api/v1/vehicles?country=GERMANY
# Filter by vehicle types
GET /api/v1/vehicles?type=car,mpv,truck
# Comprehensive data
GET /api/v1/vehicles?all=true
# Specific vehicle models
GET /api/v1/vehicles/2025/tesla

🌍 Countries API

GET /countries

All countries index with filtering

GET /countries/{code}

Individual country details

Query Parameters

  • region - Filter by world region (e.g., 'Europe', 'Asia', 'Africa')
  • subregion - Filter by subregion (e.g., 'Northern Europe', 'Southern Asia')
  • all - Set to 'true' to include comprehensive data including subdivision info

Response Fields

Minimal Mode

  • β€’ name - Country name
  • β€’ iso2 - Two-letter ISO code
  • β€’ endpoint - Detail URL

Comprehensive Mode (?all=true)

  • β€’ All minimal fields plus:
  • β€’ iso3, region, subregion
  • β€’ capital, currency, phone_code
  • β€’ subdivision_type, total_subdivisions
  • β€’ subdivisions_endpoint

Examples

# Minimal countries for dropdowns
GET /api/v1/countries
# Filter by region
GET /api/v1/countries?region=Europe
# Comprehensive data with subdivision info
GET /api/v1/countries?all=true
# Individual country
GET /api/v1/countries/kosovo

πŸ—ΊοΈ Subdivisions API

Access states, provinces, departments, and other administrative subdivisions with intelligent type detection.

GET /countries/{code}/subdivisions

Get subdivisions for a specific country

Intelligent Subdivision Types

πŸ‡ΊπŸ‡Έ United States

states

πŸ‡¨πŸ‡¦ Canada

provinces

πŸ‡©πŸ‡ͺ Germany

states

πŸ‡«πŸ‡· France

departments

πŸ‡―πŸ‡΅ Japan

prefectures

πŸ‡¨πŸ‡­ Switzerland

cantons

Response Fields

Minimal Mode

  • β€’ name - Subdivision name
  • β€’ code - Official code (e.g., "CA", "TX")

Comprehensive Mode (?all=true)

  • β€’ All minimal fields plus:
  • β€’ type - Subdivision type
  • β€’ latitude, longitude - Coordinates

Examples

# US states (minimal for dropdowns)
GET /api/v1/countries/US/subdivisions
# Canadian provinces with coordinates
GET /api/v1/countries/CA/subdivisions?all=true
# German states
GET /api/v1/countries/DE/subdivisions

🌏 Regions & Subregions API

Access world regions and subregions for geographic organization and filtering.

GET /regions

World regions (7 continents)

GET /subregions

Subregions within continents

Available Regions

β€’ Africa
β€’ Antarctica
β€’ Asia
β€’ Europe
β€’ North America
β€’ Oceania
β€’ South America

Examples

# All world regions
GET /api/v1/regions
# All subregions
GET /api/v1/subregions

⚑ Caching & Performance

MatrixAPI implements aggressive multi-layer caching for exceptional performance worldwide.

Cache Layers

🏠 Application Cache

Server-side Rails caching with Redis

  • β€’ Cached for 1 year (immutable data)
  • β€’ Automatic cache invalidation on deployment
  • β€’ Sub-50ms response times

🌐 HTTP Cache

Browser & CDN caching with ETags

  • β€’ 1-year cache duration
  • β€’ ETags for conditional requests
  • β€’ 304 Not Modified responses

Cache Headers

Cache-Control: max-age=31556952, public
ETag: W/"2725d4a3b4575afe5a838dd205f326d7"
X-Runtime: 0.051136

Performance Benefits

  • β€’ Global Performance: Instant responses via CDN caching
  • β€’ Bandwidth Efficiency: 304 responses save bandwidth
  • β€’ Server Efficiency: Minimal database load
  • β€’ Developer Friendly: No cache management needed

πŸ’» Code Examples

🎯 Interactive Demo

See the API in action with live dynamic dropdowns for countries, subdivisions, cities, and vehicles.

Try Live Demo

Features: Real-time API calls, performance monitoring, and intelligent subdivision filtering

JavaScript (Fetch)

// Get minimal data for dropdowns
const response = await fetch('https://matrixapi.dev/api/v1/countries');
const data = await response.json();

// Populate dropdown
data.countries.forEach(country => {
  dropdown.innerHTML += `<option value="${country.iso2}">${country.name}</option>`;
});

// Get comprehensive data
const detailed = await fetch('https://matrixapi.dev/api/v1/countries?all=true');
const fullData = await detailed.json();

Python (Requests)

import requests

# Get vehicle data with filtering
response = requests.get('https://matrixapi.dev/api/v1/vehicles', params={
    'country': 'GERMANY',
    'type': 'car,mpv'
})
vehicles = response.json()

# Get specific vehicle models  
tesla_response = requests.get('https://matrixapi.dev/api/v1/vehicles/2025/tesla')
tesla_models = tesla_response.json()

cURL Examples

# Check cache headers
curl -I "https://matrixapi.dev/api/v1/countries/kosovo?all=true"

# Test response times (cache verification)
time curl -s "https://matrixapi.dev/api/v1/countries/kosovo?all=true" > /dev/null

# Get US states for dropdown
curl "https://matrixapi.dev/api/v1/countries/US/subdivisions" | jq '.subdivisions'

Common Use Cases

πŸŽ›οΈ Form Components

  • β€’ Country dropdowns
  • β€’ State/Province selectors
  • β€’ Vehicle make/model lists

    • πŸ“Š Data Applications

  • β€’ Geographic analysis
  • β€’ Automotive databases
  • β€’ Reference data validation