{
  "openapi": "3.1.0",
  "info": {
    "title": "Store Detector Rankings API",
    "version": "1.0.0",
    "description": "Read-only JSON API for the biggest Shopify stores by country and category, ranked by traffic. Public, no authentication required.",
    "contact": {
      "name": "Store Detector",
      "url": "https://storedetector.com"
    },
    "license": {
      "name": "Data © Store Detector"
    }
  },
  "servers": [
    {
      "url": "https://storedetector.com"
    }
  ],
  "paths": {
    "/api/health.json": {
      "get": {
        "summary": "Health / liveness + data freshness",
        "operationId": "getHealth",
        "responses": {
          "200": {
            "description": "Service status",
            "content": {
              "application/json": {}
            }
          }
        }
      }
    },
    "/api/v1/overview.json": {
      "get": {
        "summary": "Totals and index of country/category endpoints",
        "operationId": "getOverview",
        "responses": {
          "200": {
            "description": "Overview",
            "content": {
              "application/json": {}
            }
          }
        }
      }
    },
    "/api/v1/countries/{code}.json": {
      "get": {
        "summary": "Top Shopify stores in a country (ISO 3166-1 alpha-2)",
        "operationId": "getCountry",
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "US"
            },
            "description": "ISO 3166-1 alpha-2 country code (uppercase)"
          }
        ],
        "responses": {
          "200": {
            "description": "Ranked stores",
            "content": {
              "application/json": {}
            }
          },
          "404": {
            "description": "Country not published"
          }
        }
      }
    },
    "/api/v1/categories/{slug}.json": {
      "get": {
        "summary": "Top Shopify stores in a category",
        "operationId": "getCategory",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "clothing"
            },
            "description": "Category slug (e.g. clothing, beauty, electronics)"
          }
        ],
        "responses": {
          "200": {
            "description": "Ranked stores",
            "content": {
              "application/json": {}
            }
          },
          "404": {
            "description": "Category not published"
          }
        }
      }
    }
  },
  "x-dataUpdated": "2026-10-09"
}