{
  "openapi": "3.1.0",
  "info": {
    "title": "Big Mac Index API",
    "summary": "Real-time Big Mac prices, PPP data, and currency valuation signals.",
    "description": "REST API serving daily-fresh Big Mac Index data from real menu sources across multiple countries and cities. Covers country-level prices, USD conversion, implied purchasing-power-parity rates, raw and GDP-adjusted PPP valuations, market exchange rates, city-level breakdowns, multi-day history, and cross-country comparisons.\n\nThe API is free for light public use without authentication. For commercial, high-volume, or production use, contact us at https://thebigmacindex.com/api#contact.\n\nIndependent project. Inspired by the Big Mac Index concept. Not affiliated with McDonald's or The Economist.",
    "version": "1.0.0",
    "termsOfService": "https://thebigmacindex.com/api",
    "contact": {
      "name": "TheBigMacIndex.com",
      "url": "https://thebigmacindex.com/api",
      "email": "hello@thebigmacindex.com"
    },
    "license": {
      "name": "Free for light public use with attribution. Contact for commercial.",
      "url": "https://thebigmacindex.com/data"
    },
    "x-providerName": "thebigmacindex.com",
    "x-apisguru-categories": ["financial", "open_data"],
    "x-logo": {
      "url": "https://thebigmacindex.com/favicon.png",
      "backgroundColor": "#0d0a05"
    },
    "x-origin": [
      {
        "format": "openapi",
        "url": "https://thebigmacindex.com/api/openapi.json",
        "version": "3.1"
      }
    ],
    "x-unofficialSpec": false
  },
  "servers": [
    {
      "url": "https://api.thebigmacindex.com/api/v1/burger",
      "description": "Production"
    }
  ],
  "tags": [
    { "name": "Snapshot", "description": "Latest daily snapshot of country-level data." },
    { "name": "Rankings", "description": "Sorted views over the snapshot." },
    { "name": "History", "description": "Daily historical series." },
    { "name": "Comparison", "description": "Pairwise country comparisons with implied FX rates." },
    { "name": "Metadata", "description": "Country, city, currency metadata." },
    { "name": "Operations", "description": "Pipeline status." }
  ],
  "paths": {
    "/latest": {
      "get": {
        "tags": ["Snapshot"],
        "summary": "Latest country-level prices",
        "description": "Get the latest Big Mac (or cheeseburger) snapshot across all tracked countries, including local price, USD conversion, implied PPP rate, market FX, raw and GDP-adjusted PPP valuation, and city-level breakdowns.",
        "operationId": "getLatest",
        "parameters": [
          { "$ref": "#/components/parameters/CountryId" },
          { "$ref": "#/components/parameters/Item" }
        ],
        "responses": {
          "200": {
            "description": "Latest snapshot.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/LatestResponse" },
                "example": {
                  "date": "2026-05-02",
                  "usBasePrice": 5.79,
                  "countries": [
                    {
                      "countryId": "ch",
                      "countryName": "Switzerland",
                      "countryCode": "CH",
                      "currency": "CHF",
                      "localPrice": 8.9,
                      "usdPrice": 11.36,
                      "impliedPpp": 1.273247,
                      "marketFxRate": 0.783348,
                      "rawPppIndex": 62.54,
                      "gdpAdjustedIndex": 26.97,
                      "valuationLabel": "overvalued",
                      "citiesSampled": 5,
                      "cities": [
                        { "city": "Zurich", "localPrice": 9.1, "usdPrice": 11.62, "numSources": 1, "confidence": "high" }
                      ],
                      "date": "2026-05-02"
                    }
                  ],
                  "metadata": { "lastUpdated": "2026-05-02 00:13:01", "countriesCount": 9, "baseCountry": "us" }
                }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/rankings": {
      "get": {
        "tags": ["Rankings"],
        "summary": "Sortable country rankings",
        "description": "Get countries ranked by a selected metric. Useful for leaderboards, top-N tables, dashboard widgets.",
        "operationId": "getRankings",
        "parameters": [
          {
            "name": "metric",
            "in": "query",
            "description": "Which metric to rank by.",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["raw_ppp_index", "gdp_adjusted_index", "absolute_price_index", "usd_price"],
              "default": "raw_ppp_index"
            }
          },
          {
            "name": "order",
            "in": "query",
            "description": "Sort direction.",
            "required": false,
            "schema": { "type": "string", "enum": ["asc", "desc"], "default": "desc" }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Cap the number of returned rankings.",
            "required": false,
            "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }
          },
          { "$ref": "#/components/parameters/Item" }
        ],
        "responses": {
          "200": {
            "description": "Ordered list of countries with the selected metric.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/RankingsResponse" }
              }
            }
          }
        }
      }
    },
    "/history": {
      "get": {
        "tags": ["History"],
        "summary": "Daily historical series for a country",
        "description": "Get daily Big Mac price history for a country, including local and USD price, raw and GDP-adjusted PPP indices, and absolute price index. Useful for charts, trend analysis, and data journalism.",
        "operationId": "getHistory",
        "parameters": [
          {
            "name": "country",
            "in": "query",
            "description": "Country ID. Defaults to `us`.",
            "required": false,
            "schema": { "type": "string", "default": "us" }
          },
          {
            "name": "days",
            "in": "query",
            "description": "Number of days of history to return.",
            "required": false,
            "schema": { "type": "integer", "minimum": 1, "maximum": 365, "default": 30 }
          },
          { "$ref": "#/components/parameters/Item" }
        ],
        "responses": {
          "200": {
            "description": "Historical series for the requested country.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HistoryResponse" } } }
          }
        }
      }
    },
    "/compare": {
      "get": {
        "tags": ["Comparison"],
        "summary": "Cross-country comparison with implied FX rates",
        "description": "Compare 2-5 countries by current Big Mac prices, with pairwise implied PPP exchange rates derived from each country's burger price.",
        "operationId": "compareCountries",
        "parameters": [
          {
            "name": "countries",
            "in": "query",
            "description": "Comma-separated country IDs. Minimum 2, maximum 5.",
            "required": true,
            "schema": { "type": "string", "example": "us,ch,de" }
          },
          { "$ref": "#/components/parameters/Item" }
        ],
        "responses": {
          "200": {
            "description": "Country snapshot + pairwise comparison matrix.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompareResponse" } } }
          },
          "400": { "$ref": "#/components/responses/BadRequest" }
        }
      }
    },
    "/countries": {
      "get": {
        "tags": ["Metadata"],
        "summary": "All configured countries",
        "description": "List every country tracked by the API, with currency, sampled cities, and GDP-per-capita-PPP metadata.",
        "operationId": "getCountries",
        "responses": {
          "200": {
            "description": "Country metadata.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountriesResponse" } } }
          }
        }
      }
    },
    "/currencies": {
      "get": {
        "tags": ["Metadata"],
        "summary": "Currency-level data",
        "description": "Get all world currencies with exchange rates, M2 money supply, and Big Mac PPP valuation signals where available.",
        "operationId": "getCurrencies",
        "parameters": [{ "$ref": "#/components/parameters/Item" }],
        "responses": {
          "200": {
            "description": "Currency-level data.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrenciesResponse" } } }
          }
        }
      }
    },
    "/scrape/status": {
      "get": {
        "tags": ["Operations"],
        "summary": "Pipeline status & freshness",
        "description": "Returns the most recent scrape run timestamp, total number of raw scrapes accumulated, and configuration counts. Useful for status dashboards and freshness checks.",
        "operationId": "getScrapeStatus",
        "responses": {
          "200": {
            "description": "Status snapshot.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ScrapeStatusResponse" },
                "example": {
                  "lastScrape": "2026-05-02 00:12:59",
                  "totalRawScrapes": 655,
                  "countriesScraped": 13,
                  "configuredCountries": 9,
                  "configuredCities": 35,
                  "scrapeEnabled": true,
                  "apifyTokenSet": true,
                  "apifyActor": "borderline/ubereats-scraper"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "CountryId": {
        "name": "country",
        "in": "query",
        "description": "ISO-2-style country ID (e.g. `us`, `ch`, `de`). When omitted, returns all countries.",
        "required": false,
        "schema": { "type": "string", "example": "ch" }
      },
      "Item": {
        "name": "item",
        "in": "query",
        "description": "Which menu item to query. Defaults to `bigmac`.",
        "required": false,
        "schema": { "type": "string", "enum": ["bigmac", "cheeseburger"], "default": "bigmac" }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Bad request.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "NotFound": {
        "description": "Resource not found.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      }
    },
    "schemas": {
      "Country": {
        "type": "object",
        "required": ["countryId", "countryName", "currency", "localPrice", "usdPrice"],
        "properties": {
          "countryId": { "type": "string", "description": "ISO-2-style lowercase country ID (e.g. `ch`).", "example": "ch" },
          "countryName": { "type": "string", "example": "Switzerland" },
          "countryCode": { "type": "string", "description": "ISO 3166-1 alpha-2 uppercase.", "example": "CH" },
          "currency": { "type": "string", "description": "ISO 4217 currency code.", "example": "CHF" },
          "localPrice": { "type": "number", "description": "Big Mac price in local currency.", "example": 8.9 },
          "usdPrice": { "type": "number", "description": "Big Mac price converted to USD at the daily market FX rate.", "example": 11.36 },
          "impliedPpp": { "type": "number", "description": "Implied PPP rate (local price ÷ US price).", "example": 1.273247 },
          "marketFxRate": { "type": "number", "description": "Market FX rate (local currency per USD).", "example": 0.783348 },
          "rawPppIndex": { "type": "number", "description": "Raw PPP valuation %. Positive = overvalued vs USD.", "example": 62.54 },
          "gdpAdjustedIndex": { "type": "number", "description": "GDP-adjusted PPP valuation %.", "example": 26.97 },
          "absolutePriceIndex": { "type": "number", "description": "Absolute price level vs US benchmark = 100.", "example": 162.52 },
          "valuationLabel": { "type": "string", "enum": ["overvalued", "undervalued", "fair"], "example": "overvalued" },
          "deliveryFeeUsd": { "type": ["number", "null"], "description": "Delivery fee where applicable.", "example": null },
          "citiesSampled": { "type": "integer", "example": 5 },
          "cities": { "type": "array", "items": { "$ref": "#/components/schemas/City" } },
          "date": { "type": "string", "format": "date", "example": "2026-05-02" }
        }
      },
      "City": {
        "type": "object",
        "required": ["city", "localPrice", "usdPrice"],
        "properties": {
          "city": { "type": "string", "example": "Zurich" },
          "localPrice": { "type": "number", "example": 9.1 },
          "usdPrice": { "type": "number", "example": 11.62 },
          "numSources": { "type": "integer", "example": 1 },
          "confidence": { "type": "string", "enum": ["high", "medium", "low"], "example": "high" }
        }
      },
      "LatestResponse": {
        "type": "object",
        "properties": {
          "date": { "type": "string", "format": "date" },
          "usBasePrice": { "type": "number", "description": "US Big Mac price used as the index anchor.", "example": 5.79 },
          "countries": { "type": "array", "items": { "$ref": "#/components/schemas/Country" } },
          "metadata": { "$ref": "#/components/schemas/SnapshotMetadata" }
        }
      },
      "RankingsResponse": {
        "type": "object",
        "properties": {
          "metric": { "type": "string", "example": "usd_price" },
          "order": { "type": "string", "example": "desc" },
          "date": { "type": "string", "format": "date" },
          "rankings": {
            "type": "array",
            "items": {
              "allOf": [
                { "$ref": "#/components/schemas/Country" },
                { "type": "object", "properties": { "rank": { "type": "integer", "example": 1 }, "valuationPct": { "type": "number", "example": 62.54 } } }
              ]
            }
          }
        }
      },
      "HistoryResponse": {
        "type": "object",
        "properties": {
          "country": { "type": "string", "example": "ch" },
          "countryName": { "type": "string", "example": "Switzerland" },
          "currency": { "type": "string", "example": "CHF" },
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "date": { "type": "string", "format": "date" },
                "localPrice": { "type": "number" },
                "usdPrice": { "type": "number" },
                "rawPppIndex": { "type": "number" },
                "gdpAdjustedIndex": { "type": "number" },
                "absolutePriceIndex": { "type": "number" }
              }
            }
          },
          "meta": { "type": "object", "additionalProperties": true }
        }
      },
      "CompareResponse": {
        "type": "object",
        "properties": {
          "countries": { "type": "array", "items": { "$ref": "#/components/schemas/Country" } },
          "comparisons": {
            "type": "array",
            "description": "Pairwise comparison rows.",
            "items": {
              "type": "object",
              "properties": {
                "from": { "type": "string", "example": "us" },
                "to": { "type": "string", "example": "ch" },
                "impliedFx": { "type": "number" },
                "marketFx": { "type": "number" },
                "valuationPct": { "type": "number" }
              }
            }
          }
        }
      },
      "CountriesResponse": {
        "type": "object",
        "properties": {
          "countries": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["id", "name", "currency"],
              "properties": {
                "id": { "type": "string", "example": "ch" },
                "name": { "type": "string", "example": "Switzerland" },
                "code": { "type": "string", "example": "CH" },
                "currency": { "type": "string", "example": "CHF" },
                "gdpPerCapitaPpp": { "type": "number", "example": 84658 },
                "cities": { "type": "array", "items": { "type": "string" }, "example": ["Zurich", "Geneva"] }
              }
            }
          },
          "meta": { "type": "object", "additionalProperties": true }
        }
      },
      "CurrenciesResponse": {
        "type": "object",
        "properties": {
          "currencies": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "code": { "type": "string", "example": "CHF" },
                "name": { "type": "string", "example": "Swiss Franc" },
                "flag": { "type": "string", "example": "🇨🇭" },
                "price": { "type": "number", "description": "Spot rate vs USD." },
                "rateChange": { "type": "number" },
                "marketCapUsd": { "type": ["number", "null"] },
                "circulatingSupply": { "type": ["number", "null"] },
                "symbol": { "type": "string" },
                "bigmac": {
                  "type": ["object", "null"],
                  "description": "Big Mac PPP signal for this currency, if data is available.",
                  "properties": {
                    "rawPppIndex": { "type": "number" },
                    "gdpAdjustedIndex": { "type": "number" },
                    "valuationLabel": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      },
      "ScrapeStatusResponse": {
        "type": "object",
        "properties": {
          "lastScrape": { "type": "string", "example": "2026-05-02 00:12:59" },
          "totalRawScrapes": { "type": "integer", "example": 655 },
          "countriesScraped": { "type": "integer", "example": 13 },
          "configuredCountries": { "type": "integer", "example": 9 },
          "configuredCities": { "type": "integer", "example": 35 },
          "scrapeEnabled": { "type": "boolean", "example": true },
          "apifyTokenSet": { "type": "boolean", "example": true },
          "apifyActor": { "type": "string", "example": "borderline/ubereats-scraper" }
        }
      },
      "SnapshotMetadata": {
        "type": "object",
        "properties": {
          "lastUpdated": { "type": "string", "example": "2026-05-02 00:13:01" },
          "countriesCount": { "type": "integer", "example": 9 },
          "baseCountry": { "type": "string", "example": "us" }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": false },
          "error": {
            "type": "object",
            "properties": {
              "code": { "type": "string", "example": "INVALID_COUNTRY" },
              "message": { "type": "string", "example": "Country ID not found." },
              "details": { "type": "object", "additionalProperties": true }
            }
          }
        }
      }
    }
  }
}