API Documentation - MatrixAPI

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 -H "X-API-Key: your_api_key_here" https://matrixapi.dev/api/v1/vehicles

# Get comprehensive vehicle data  
curl -H "X-API-Key: your_api_key_here" https://matrixapi.dev/api/v1/vehicles?all=true

# Get specific vehicle models
curl -H "X-API-Key: your_api_key_here" https://matrixapi.dev/api/v1/vehicles/2025/bmw

Authentication

MatrixAPI offers both free and premium endpoints with different authentication requirements.

🌍 Geographic Data (Free): Countries, subdivisions, and cities - no authentication required.

🚗 Vehicle Data (Premium): Requires API key in production. Free during development/testing.

API Key Usage

For endpoints that require authentication, include your API key in the request header:

# Include API key in header
curl -H "X-API-Key: your_api_key_here" https://matrixapi.dev/api/v1/vehicles

# For JavaScript/fetch
fetch('https://matrixapi.dev/api/v1/vehicles', {
  headers: {
    'X-API-Key': 'your_api_key_here'
  }
})

Getting an API Key: Contact us to request production access for vehicle data endpoints.

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": "bmw",
      "endpoint": "/api/v1/vehicles/2025/bmw"
    }
  ],
  "total": 99,
  "statistics": {...}
}

📊 Comprehensive (?all=true)

Complete data with all available fields

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

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

⚠️ Authentication Required: Vehicle API endpoints require an API key in production. See authentication section for details.

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
curl -H "X-API-Key: your_api_key" https://matrixapi.dev/api/v1/vehicles

# Filter by country
curl -H "X-API-Key: your_api_key" https://matrixapi.dev/api/v1/vehicles?country=GERMANY

# Filter by vehicle types
curl -H "X-API-Key: your_api_key" https://matrixapi.dev/api/v1/vehicles?type=car,mpv,truck

# Comprehensive data
curl -H "X-API-Key: your_api_key" https://matrixapi.dev/api/v1/vehicles?all=true

# Specific vehicle models
curl -H "X-API-Key: your_api_key" https://matrixapi.dev/api/v1/vehicles/2025/bmw

🌍 Countries API

Access countries, subdivisions, and cities with comprehensive geographic data. All endpoints support human-readable, case-insensitive names.

GET /countries

All countries index with filtering

GET /countries/{identifier}

Individual country details (supports names)

🔗 Connected Resources

Countries API seamlessly connects to:

• Subdivisions: /countries/{country}/subdivisions

• Cities: /countries/{country}/{subdivision}/cities

• Specific Cities: /countries/{country}/{subdivision}/{city}

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

# Individual country (human-readable)
GET /api/v1/countries/kosovo

# Get subdivisions for a country
GET /api/v1/countries/kosovo/subdivisions

# Get cities in a subdivision
GET /api/v1/countries/kosovo/ferizaj/cities

🏙️ Cities API

Access cities within specific subdivisions with coordinates and comprehensive data. All endpoints support human-readable, case-insensitive names.

GET /countries/{country}/{subdivision}/cities

All cities in a subdivision

GET /countries/{country}/{subdivision}/{city}

Specific city details

Human-Readable URLs

All parameters support case-insensitive, human-readable names:

• /countries/kosovo/ferizaj/cities (human-readable)

• /countries/XK/XUF/cities (formal codes)

• /countries/Kosovo/Ferizaj/cities (mixed case)

Query Parameters

all - Set to 'true' to include comprehensive data with coordinates

Response Fields

Minimal Mode

• id - City ID
• name - City name

Comprehensive Mode (?all=true)

• All minimal fields plus:
• latitude - GPS latitude
• longitude - GPS longitude

Examples

# Cities in Kosovo's Ferizaj district
GET /api/v1/countries/kosovo/ferizaj/cities

# Cities with coordinates (included by default)
GET /api/v1/countries/kosovo/ferizaj/cities

# Specific city details
GET /api/v1/countries/kosovo/ferizaj/shtime

Sample Response

{
  "country": "Kosovo",
  "subdivision": "Ferizaj", 
  "subdivision_code": "XUF",
  "subdivision_type": "districts",
  "cities": [
    {
      "id": 157206,
      "name": "Ferizaj"
    },
    {
      "id": 157207,
      "name": "Shtime"
    }
  ],
  "total": 5,
  "examples": {
    "all_subdivisions": "/api/v1/countries/kosovo/subdivisions"
  }
}

🗺️ 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 (coordinates included by default)
GET /api/v1/countries/CA/subdivisions

# 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>`;
});

// Data already includes all available fields by default
console.log(data.countries[0].currency); // Currency info included
console.log(data.countries[0].latitude); // Coordinates included

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  
bmw_response = requests.get('https://matrixapi.dev/api/v1/vehicles/2025/bmw')
bmw_models = bmw_response.json()

cURL Examples

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

# Test response times (cache verification)
time curl -s "https://matrixapi.dev/api/v1/countries/kosovo" > /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