{
  "openapi": "3.1.0",
  "info": {
    "title": "Ехай — открытые данные о ценах на топливо",
    "version": "1.0.0",
    "summary": "Агрегированные цены на АИ-92, АИ-95, ДТ и газ по сетям АЗС и регионам России.",
    "description": "Публичный доступ без ключа и без ограничений по частоте в разумных пределах. Данные обновляются несколько раз в сутки. Это выборка по сетям, с которыми есть прямой обмен данными, а не официальная статистика Росстата. Источник указывать как «Ехай» (eh-ai.ru).",
    "contact": {
      "name": "Поддержка «Ехай»",
      "email": "help@eh-ai.ru",
      "url": "https://eh-ai.ru/"
    },
    "license": {
      "name": "CC BY 4.0",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    }
  },
  "servers": [
    {
      "url": "https://eh-ai.ru",
      "description": "Продакшн"
    }
  ],
  "paths": {
    "/assets/prices.json": {
      "get": {
        "operationId": "getCurrentPrices",
        "summary": "Текущий срез цен",
        "description": "Медианные цены по сетям АЗС и по регионам России плюс перцентили по стране.",
        "responses": {
          "200": {
            "description": "Срез цен",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PriceSnapshot"
                }
              }
            }
          }
        }
      }
    },
    "/assets/prices-history.json": {
      "get": {
        "operationId": "getPriceHistory",
        "summary": "Ежедневная история цен",
        "description": "Одна запись в сутки: медианы и перцентили по стране.",
        "responses": {
          "200": {
            "description": "Массив суточных записей",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/HistoryRow"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/assets/prices.csv": {
      "get": {
        "operationId": "getPricesCsv",
        "summary": "Цены плоской таблицей",
        "description": "Те же данные, что в prices.json, но одной таблицей: type (region|brand), name, ai92, ai95, dt, gas, stations, updated.",
        "responses": {
          "200": {
            "description": "CSV",
            "content": {
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "PriceSnapshot": {
        "type": "object",
        "required": [
          "updated",
          "updated_h",
          "stations",
          "range95",
          "brands",
          "regions"
        ],
        "properties": {
          "updated": {
            "type": "integer",
            "description": "Время сборки среза, unix-секунды UTC"
          },
          "updated_h": {
            "type": "string",
            "description": "Дата среза в формате ДД.ММ.ГГГГ",
            "examples": [
              "16.08.2026"
            ]
          },
          "stations": {
            "type": "integer",
            "description": "Число АЗС в выборке этого среза"
          },
          "range95": {
            "type": "object",
            "description": "Разброс цены АИ-95 ПО ВСЕЙ СТРАНЕ. Не выгода конкретного водителя: между соседними АЗС разница обычно 5–10 ₽.",
            "required": [
              "min",
              "max"
            ],
            "properties": {
              "min": {
                "type": "number",
                "description": "5-й перцентиль, ₽/л"
              },
              "max": {
                "type": "number",
                "description": "95-й перцентиль, ₽/л"
              }
            }
          },
          "brands": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PriceGroup"
            }
          },
          "regions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PriceGroup"
            }
          }
        }
      },
      "PriceGroup": {
        "type": "object",
        "description": "Медианы по сети АЗС или по региону",
        "required": [
          "name",
          "n"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Название сети или региона"
          },
          "n": {
            "type": "integer",
            "description": "Число станций в выборке"
          },
          "ai92": {
            "type": "number",
            "description": "Медиана АИ-92, ₽/л"
          },
          "ai95": {
            "type": "number",
            "description": "Медиана АИ-95, ₽/л"
          },
          "dt": {
            "type": "number",
            "description": "Медиана дизельного топлива, ₽/л"
          },
          "gas": {
            "type": "number",
            "description": "Медиана газа (СУГ), ₽/л"
          }
        }
      },
      "HistoryRow": {
        "type": "object",
        "properties": {
          "d": {
            "type": "string",
            "description": "Дата, ГГГГ-ММ-ДД"
          },
          "min95": {
            "type": "number"
          },
          "max95": {
            "type": "number"
          },
          "ai92": {
            "type": "number"
          },
          "ai95": {
            "type": "number"
          },
          "dt": {
            "type": "number"
          }
        }
      }
    }
  }
}