API Documentation

{
  "[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
}

• country - Filter by manufacturer country — ISO2 code (DE) or full name (GERMANY)
• type - Filter by vehicle type (car, mpv, truck, motorcycle, all) - supports comma-separated
• all - Set to 'true' to include comprehensive data fields

• region - Filter by world region (e.g., 'Europe', 'Asia', 'Africa')
• subregion - Filter by subregion (e.g., 'Northern Europe', 'Southern Asia')

All fields are always returned — there is no minimal/comprehensive toggle for countries.

• • name, iso2, iso3, numeric_code, phone_code
• • capital, region, subregion
• • currency, currency_name, currency_symbol
• • tld, native_name, nationality, primary_language
• • driving_side, landlocked, un_member
• • population, area, density, gdp_per_capita, median_age
• • subdivision_type, total_subdivisions, subdivisions_endpoint
• • emoji, emojiU, latitude, longitude
• • timezones, translations, endpoint

Coordinates and endpoint are always included — no query parameter required.

• • id - City database ID
• • name - City name
• • latitude - GPS latitude
• • longitude - GPS longitude
• • endpoint - City detail URL

Note: If city data was recently AI-populated, cache_duration may be "no-cache" on first access. Subsequent requests return "immutable".

{
  "country": "Kosovo",
  "subdivision": "Ferizaj",
  "subdivision_code": "XUF",
  "subdivision_type": "districts",
  "cities": [
            {
      "id": 157206,
      "name": "Ferizaj",
      "latitude": "42.3708",
      "longitude": "21.1531",
      "endpoint": "https://matrixapi.dev/api/v1/countries/kosovo/ferizaj/ferizaj"
    },
    {
      "id": 157207,
      "name": "Shtime",
      "latitude": "42.4333",
      "longitude": "21.04",
      "endpoint": "https://matrixapi.dev/api/v1/countries/kosovo/ferizaj/shtime"
    }
  ],
  "total": 5,
  "data_source": "database",
  "cache_duration": "immutable",
  "canonical_url": "https://matrixapi.dev/api/v1/countries/XK/subdivisions/XUF/cities",
  "url_note": "Both /countries/{name}/{subdivision}/cities and /countries/{iso2}/subdivisions/{code}/cities return identical data. The canonical form uses ISO codes.",
  "related_endpoints": {
    "cross_subdivision_search": "https://matrixapi.dev/api/v1/cities?country=XK",
    "note": "Use /api/v1/cities?country={iso2}&state={code} to search across multiple subdivisions"
  },
  "available_fields": ["id", "name", "latitude", "longitude", "endpoint"]
}

All fields are always returned for each subdivision.

• • name - Subdivision name
• • code - Official code (e.g., "US-CA", "XK-XUF")
• • type - Subdivision type (state, province, district, etc.)
• • latitude, longitude - Geographic center coordinates
• • cities_count - Number of cities in this subdivision
• • endpoint - URL to fetch cities for this subdivision

• • code — ISO 4217 code (e.g., USD, EUR)
• • name — Official currency name
• • symbol — Currency symbol (e.g., $, €)
• • decimal_places — Number of decimal digits
• • countries — ISO2 codes of countries using this currency

• country — ISO2 country code (e.g., US, DE)
• type — Airport type: large_airport, medium_airport, small_airport, heliport, seaplane_base, balloonport, closed
• continent — Continent code: AF, AN, AS, EU, NA, OC, SA
• region — Geographic region name (e.g., Europe)
• subregion — Geographic subregion (e.g., Western Europe)
• iata — Look up by IATA code (e.g., JFK)
• all — Set to true for full fields including coordinates, ICAO, elevation

• • service — Service name
• • version — API version
• • status — Operational status
• • available_apis — Map of all APIs with endpoint and status
• • data_coverage — Statistics per data category

{
  "service": "MatrixAPI",
  "version": "v1",
  "status": "operational",
  "uptime": "99.9%",
  "cache_strategy": "immutable",
  "available_apis": {
    "vehicles":          { "endpoint": "/api/v1/vehicles",   "status": "available" },
    "countries":         { "endpoint": "/api/v1/countries",  "status": "available" },
    "currencies":        { "endpoint": "/api/v1/currencies", "status": "available" },
    "airports":          { "endpoint": "/api/v1/airports",   "status": "available" },
    "languages":         { "endpoint": "/api/v1/languages",  "status": "coming_soon" },
    "holidays":          { "endpoint": "/api/v1/holidays",   "status": "coming_soon" },
    "phone_metadata":    { "endpoint": "/api/v1/phone_metadata", "status": "coming_soon" },
    "postal_patterns":   { "endpoint": "/api/v1/postal_patterns", "status": "coming_soon" },
    "measurement_units": { "endpoint": "/api/v1/units",      "status": "coming_soon" }
  },
  "documentation": "https://matrixapi.dev/docs",
  "support": "support@matrixapi.dev"
}

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