{
 "openapi": "3.1.0",
 "info": {
  "title": "Fast Food Index API",
  "version": "1.0.0",
  "description": "Live fast food prices from 10 US chains: Big Mac Index by state, chain medians & price changes.\n\nFast Food Index tracks real menu prices at 54,000+ US restaurants across 10 major chains, collected from the chains' own online ordering systems. Get national and state-level medians, the Big Mac Index by state, item prices, and verified price changes \u2014 free, no API key, updated weekly.",
  "contact": {
   "name": "Fast Food Index",
   "url": "https://fastfoodindex.com/api/"
  },
  "license": {
   "name": "Free with attribution",
   "url": "https://fastfoodindex.com/api/"
  }
 },
 "servers": [
  {
   "url": "https://fastfoodindex.com",
   "description": "Production (static JSON snapshots, refreshed weekly)"
  }
 ],
 "externalDocs": {
  "description": "API & MCP documentation",
  "url": "https://fastfoodindex.com/api/"
 },
 "tags": [
  {
   "name": "Fast Food Prices",
   "description": "US fast food menu price snapshots: chain medians, the Big Mac Index, state prices and price changes."
  }
 ],
 "paths": {
  "/api/v1/chains.json": {
   "get": {
    "tags": [
     "Fast Food Prices"
    ],
    "operationId": "listChains",
    "summary": "All chains and their flagship medians",
    "description": "Every chain Fast Food Index prices: its flagship item, the item's national median and range, and how many restaurants were priced.",
    "responses": {
     "200": {
      "description": "The current snapshot file.",
      "content": {
       "application/json": {
        "schema": {
         "allOf": [
          {
           "$ref": "#/components/schemas/Envelope"
          },
          {
           "type": "object",
           "properties": {
            "chains": {
             "type": "array",
             "items": {
              "$ref": "#/components/schemas/ChainRow"
             }
            },
            "collection": {
             "type": "object",
             "properties": {
              "restaurants_priced": {
               "type": [
                "integer",
                "null"
               ]
              },
              "price_observations": {
               "type": [
                "integer",
                "null"
               ]
              },
              "chains": {
               "type": "integer"
              }
             }
            }
           },
           "required": [
            "chains",
            "collection"
           ]
          }
         ]
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/chains/{chain}.json": {
   "get": {
    "tags": [
     "Fast Food Prices"
    ],
    "operationId": "getChainDetail",
    "summary": "One chain in full",
    "description": "One chain's flagship item with per-state medians, plus item medians for the chain's most widely priced items.",
    "parameters": [
     {
      "name": "chain",
      "in": "path",
      "required": true,
      "description": "Chain slug.",
      "schema": {
       "type": "string",
       "enum": [
        "burger-king",
        "chick-fil-a",
        "chipotle",
        "dominos",
        "kfc",
        "mcdonalds",
        "papa-johns",
        "popeyes",
        "taco-bell",
        "wendys"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "The current snapshot file.",
      "content": {
       "application/json": {
        "schema": {
         "allOf": [
          {
           "$ref": "#/components/schemas/Envelope"
          },
          {
           "type": "object",
           "properties": {
            "chain": {
             "type": "string"
            },
            "chain_name": {
             "type": "string"
            },
            "url": {
             "type": "string",
             "format": "uri"
            },
            "restaurants_priced": {
             "type": "integer"
            },
            "items_priced": {
             "type": "integer"
            },
            "items_included": {
             "type": "integer"
            },
            "flagship": {
             "anyOf": [
              {
               "$ref": "#/components/schemas/FlagshipSummary"
              },
              {
               "type": "null"
              }
             ]
            },
            "items": {
             "type": "array",
             "items": {
              "$ref": "#/components/schemas/ItemSummary"
             }
            }
           },
           "required": [
            "chain",
            "chain_name",
            "url",
            "restaurants_priced",
            "items_priced",
            "items_included",
            "flagship",
            "items"
           ]
          }
         ]
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/big-mac-index.json": {
   "get": {
    "tags": [
     "Fast Food Prices"
    ],
    "operationId": "getBigMacIndex",
    "summary": "The Big Mac Index by state",
    "description": "The national Big Mac median, range and extremes, and the median by state with each state against the national figure. States with fewer than 5 priced restaurants are omitted.",
    "responses": {
     "200": {
      "description": "The current snapshot file.",
      "content": {
       "application/json": {
        "schema": {
         "allOf": [
          {
           "$ref": "#/components/schemas/Envelope"
          },
          {
           "type": "object",
           "properties": {
            "item": {
             "type": "string"
            },
            "chain": {
             "type": "string"
            },
            "url": {
             "type": "string",
             "format": "uri"
            },
            "national": {
             "type": "object",
             "properties": {
              "median": {
               "type": [
                "number",
                "null"
               ]
              },
              "mean": {
               "type": [
                "number",
                "null"
               ]
              },
              "restaurants_priced": {
               "type": "integer"
              },
              "range": {
               "type": "object",
               "properties": {
                "lo": {
                 "type": [
                  "number",
                  "null"
                 ]
                },
                "hi": {
                 "type": [
                  "number",
                  "null"
                 ]
                },
                "p10": {
                 "type": [
                  "number",
                  "null"
                 ]
                },
                "p90": {
                 "type": [
                  "number",
                  "null"
                 ]
                }
               },
               "required": [
                "lo",
                "hi",
                "p10",
                "p90"
               ]
              },
              "cheapest_store": {
               "anyOf": [
                {
                 "$ref": "#/components/schemas/StoreExtreme"
                },
                {
                 "type": "null"
                }
               ]
              },
              "priciest_store": {
               "anyOf": [
                {
                 "$ref": "#/components/schemas/StoreExtreme"
                },
                {
                 "type": "null"
                }
               ]
              }
             },
             "required": [
              "median",
              "mean",
              "restaurants_priced",
              "range",
              "cheapest_store",
              "priciest_store"
             ]
            },
            "states": {
             "type": "array",
             "items": {
              "$ref": "#/components/schemas/BigMacState"
             }
            },
            "states_note": {
             "type": "string"
            }
           },
           "required": [
            "item",
            "chain",
            "url",
            "national",
            "states",
            "states_note"
           ]
          }
         ]
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/states.json": {
   "get": {
    "tags": [
     "Fast Food Prices"
    ],
    "operationId": "listStates",
    "summary": "Fast food prices by state",
    "description": "Every state ranked by a basket index comparing the median price of the same core items in that state against their national medians, with the flagship medians per state.",
    "responses": {
     "200": {
      "description": "The current snapshot file.",
      "content": {
       "application/json": {
        "schema": {
         "allOf": [
          {
           "$ref": "#/components/schemas/Envelope"
          },
          {
           "type": "object",
           "properties": {
            "url": {
             "type": "string",
             "format": "uri"
            },
            "method": {
             "type": "string"
            },
            "national_flagship_medians": {
             "type": "object",
             "properties": {
              "big_mac": {
               "type": [
                "number",
                "null"
               ]
              },
              "whopper": {
               "type": [
                "number",
                "null"
               ]
              },
              "cfa_chicken_sandwich": {
               "type": [
                "number",
                "null"
               ]
              },
              "crunchwrap": {
               "type": [
                "number",
                "null"
               ]
              }
             }
            },
            "flagship_columns": {
             "type": "object",
             "additionalProperties": {
              "type": "string"
             }
            },
            "collection": {
             "type": "object",
             "properties": {
              "restaurants_priced": {
               "type": [
                "integer",
                "null"
               ]
              },
              "price_observations": {
               "type": [
                "integer",
                "null"
               ]
              },
              "core_items": {
               "type": [
                "integer",
                "null"
               ]
              }
             }
            },
            "states": {
             "type": "array",
             "items": {
              "$ref": "#/components/schemas/StateRow"
             }
            }
           },
           "required": [
            "url",
            "method",
            "national_flagship_medians",
            "flagship_columns",
            "collection",
            "states"
           ]
          }
         ]
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/price-changes.json": {
   "get": {
    "tags": [
     "Fast Food Prices"
    ],
    "operationId": "getPriceChanges",
    "summary": "Latest verified price changes",
    "description": "The latest gated repricing events: the same item, the same old and new price, at 40+ restaurants in the round \u2014 never a menu restructure or a single restaurant's till.",
    "responses": {
     "200": {
      "description": "The current snapshot file.",
      "content": {
       "application/json": {
        "schema": {
         "allOf": [
          {
           "$ref": "#/components/schemas/Envelope"
          },
          {
           "type": "object",
           "properties": {
            "url": {
             "type": "string",
             "format": "uri"
            },
            "window": {
             "type": "array",
             "items": {
              "type": "string"
             }
            },
            "gate": {
             "type": "string"
            },
            "events": {
             "type": "array",
             "items": {
              "$ref": "#/components/schemas/PriceChangeEvent"
             }
            }
           },
           "required": [
            "url",
            "window",
            "gate",
            "events"
           ]
          }
         ]
        }
       }
      }
     }
    }
   }
  }
 },
 "components": {
  "schemas": {
   "Envelope": {
    "type": "object",
    "properties": {
     "generated_at": {
      "type": "string",
      "format": "date-time"
     },
     "data_through": {
      "type": "string",
      "format": "date"
     },
     "source": {
      "type": "string"
     },
     "source_url": {
      "type": "string",
      "format": "uri"
     },
     "cite": {
      "type": "string"
     },
     "updates": {
      "type": "string"
     }
    },
    "required": [
     "generated_at",
     "data_through",
     "source",
     "source_url",
     "cite",
     "updates"
    ]
   },
   "PriceRange": {
    "type": "object",
    "properties": {
     "lo": {
      "type": [
       "number",
       "null"
      ]
     },
     "hi": {
      "type": [
       "number",
       "null"
      ]
     },
     "p10": {
      "type": [
       "number",
       "null"
      ]
     },
     "p90": {
      "type": [
       "number",
       "null"
      ]
     }
    },
    "required": [
     "lo",
     "hi",
     "p10",
     "p90"
    ]
   },
   "StoreExtreme": {
    "type": "object",
    "properties": {
     "price": {
      "type": [
       "number",
       "null"
      ]
     },
     "city": {
      "type": [
       "string",
       "null"
      ]
     },
     "state": {
      "type": [
       "string",
       "null"
      ]
     }
    },
    "required": [
     "price",
     "city",
     "state"
    ]
   },
   "ItemSummary": {
    "type": "object",
    "properties": {
     "item": {
      "type": "string"
     },
     "median": {
      "type": [
       "number",
       "null"
      ]
     },
     "mean": {
      "type": [
       "number",
       "null"
      ]
     },
     "restaurants_priced": {
      "type": "integer"
     },
     "range": {
      "type": "object",
      "properties": {
       "lo": {
        "type": [
         "number",
         "null"
        ]
       },
       "hi": {
        "type": [
         "number",
         "null"
        ]
       },
       "p10": {
        "type": [
         "number",
         "null"
        ]
       },
       "p90": {
        "type": [
         "number",
         "null"
        ]
       }
      },
      "required": [
       "lo",
       "hi",
       "p10",
       "p90"
      ]
     },
     "cheapest_store": {
      "anyOf": [
       {
        "$ref": "#/components/schemas/StoreExtreme"
       },
       {
        "type": "null"
       }
      ]
     },
     "priciest_store": {
      "anyOf": [
       {
        "$ref": "#/components/schemas/StoreExtreme"
       },
       {
        "type": "null"
       }
      ]
     }
    },
    "required": [
     "item",
     "median",
     "mean",
     "restaurants_priced",
     "range",
     "cheapest_store",
     "priciest_store"
    ]
   },
   "StateMedian": {
    "type": "object",
    "properties": {
     "state": {
      "type": "string"
     },
     "median": {
      "type": [
       "number",
       "null"
      ]
     },
     "n": {
      "type": "integer"
     }
    },
    "required": [
     "state",
     "median",
     "n"
    ]
   },
   "FlagshipSummary": {
    "allOf": [
     {
      "$ref": "#/components/schemas/ItemSummary"
     },
     {
      "type": "object",
      "properties": {
       "label": {
        "type": "string"
       },
       "state_medians": {
        "type": "array",
        "items": {
         "type": "object",
         "properties": {
          "state": {
           "type": "string"
          },
          "median": {
           "type": [
            "number",
            "null"
           ]
          },
          "n": {
           "type": "integer"
          }
         },
         "required": [
          "state",
          "median",
          "n"
         ]
        }
       }
      },
      "required": [
       "label",
       "state_medians"
      ]
     }
    ]
   },
   "ChainRow": {
    "type": "object",
    "properties": {
     "chain": {
      "type": "string"
     },
     "chain_name": {
      "type": "string"
     },
     "url": {
      "type": "string",
      "format": "uri"
     },
     "restaurants_priced": {
      "type": "integer"
     },
     "items_priced": {
      "type": "integer"
     },
     "detail": {
      "type": "string",
      "format": "uri"
     },
     "flagship_item": {
      "type": "string"
     },
     "flagship_median": {
      "type": [
       "number",
       "null"
      ]
     },
     "flagship_restaurants": {
      "type": "integer"
     },
     "flagship_range": {
      "type": "object",
      "properties": {
       "lo": {
        "type": [
         "number",
         "null"
        ]
       },
       "hi": {
        "type": [
         "number",
         "null"
        ]
       },
       "p10": {
        "type": [
         "number",
         "null"
        ]
       },
       "p90": {
        "type": [
         "number",
         "null"
        ]
       }
      },
      "required": [
       "lo",
       "hi",
       "p10",
       "p90"
      ]
     }
    },
    "required": [
     "chain",
     "chain_name",
     "url",
     "restaurants_priced",
     "items_priced",
     "detail"
    ]
   },
   "BigMacState": {
    "type": "object",
    "properties": {
     "state": {
      "type": "string"
     },
     "median": {
      "type": [
       "number",
       "null"
      ]
     },
     "n": {
      "type": "integer"
     },
     "pct_vs_national": {
      "type": [
       "number",
       "null"
      ]
     }
    },
    "required": [
     "state",
     "median",
     "n",
     "pct_vs_national"
    ]
   },
   "StateRow": {
    "type": "object",
    "properties": {
     "state": {
      "type": "string"
     },
     "state_name": {
      "type": "string"
     },
     "rank": {
      "type": "integer"
     },
     "pct_vs_national": {
      "type": [
       "number",
       "null"
      ]
     },
     "basket_items": {
      "type": "integer"
     },
     "stores": {
      "type": "integer"
     },
     "chains": {
      "type": "integer"
     },
     "flagship_medians": {
      "type": "object",
      "properties": {
       "big_mac": {
        "type": [
         "number",
         "null"
        ]
       },
       "whopper": {
        "type": [
         "number",
         "null"
        ]
       },
       "cfa_chicken_sandwich": {
        "type": [
         "number",
         "null"
        ]
       },
       "crunchwrap": {
        "type": [
         "number",
         "null"
        ]
       }
      }
     }
    },
    "required": [
     "state",
     "state_name",
     "rank",
     "pct_vs_national",
     "basket_items",
     "stores",
     "chains",
     "flagship_medians"
    ]
   },
   "PriceChangeEvent": {
    "type": "object",
    "properties": {
     "chain": {
      "type": "string"
     },
     "chain_name": {
      "type": "string"
     },
     "item": {
      "type": "string"
     },
     "was": {
      "type": [
       "number",
       "null"
      ]
     },
     "now": {
      "type": [
       "number",
       "null"
      ]
     },
     "delta": {
      "type": [
       "number",
       "null"
      ]
     },
     "pct_change": {
      "type": [
       "number",
       "null"
      ]
     },
     "n_stores": {
      "type": [
       "integer",
       "null"
      ]
     }
    },
    "required": [
     "chain",
     "chain_name",
     "item",
     "was",
     "now",
     "delta",
     "pct_change",
     "n_stores"
    ]
   }
  }
 }
}