{
  "openapi": "3.1.0",
  "info": {
    "title": "eSIM Advice Public Data API",
    "version": "1.0.0",
    "description": "Free, no-key read access to live travel eSIM plan data: 70,000+ plans from 23 providers across 222 countries, re-synced from provider feeds daily. Attribution required when republishing (see https://esimadvice.com/developers). Responses are cached ~1 hour at the edge.",
    "contact": {
      "name": "eSIM Advice Editorial Team",
      "url": "https://esimadvice.com/contact",
      "email": "contact@esimadvice.com"
    },
    "license": {
      "name": "CC BY 4.0 (data)",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    }
  },
  "servers": [
    {
      "url": "https://esimadvice.com"
    }
  ],
  "paths": {
    "/api/countries/{slug}/plans": {
      "get": {
        "operationId": "listCountryPlans",
        "summary": "Plans available for a destination country",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "japan",
            "description": "Country slug, e.g. japan, france, united-states. Directory: https://esimadvice.com/countries"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "maximum": 100,
              "default": 30
            }
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "cheapest",
                "price-per-gb",
                "most-data",
                "longest-validity"
              ],
              "default": "cheapest"
            },
            "description": "cheapest and price-per-gb sort by coupon-applied price"
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Opaque pagination cursor from nextCursor"
          },
          {
            "name": "min_gb",
            "in": "query",
            "schema": {
              "type": "number"
            },
            "description": "Minimum data allowance in GB (unlimited plans always match)"
          },
          {
            "name": "validity",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "Minimum validity in days"
          },
          {
            "name": "provider",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter to one provider slug"
          },
          {
            "name": "hotspot",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            },
            "description": "Only plans that allow hotspot/tethering"
          },
          {
            "name": "unlimited",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            },
            "description": "Only unlimited plans"
          },
          {
            "name": "plan_type",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "local",
                "regional",
                "global"
              ]
            }
          },
          {
            "name": "currency",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "example": "USD",
            "description": "Display currency (USD, EUR, GBP, INR, AUD, CAD, JPY, CNY)"
          }
        ],
        "responses": {
          "200": {
            "description": "Plan list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "country": {
                      "type": "object",
                      "additionalProperties": true
                    },
                    "currency": {
                      "type": "string"
                    },
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "description": "A travel eSIM plan with display-ready labels and coupon-aware pricing.",
                        "properties": {
                          "id": {
                            "type": "integer"
                          },
                          "providerName": {
                            "type": "string"
                          },
                          "providerSlug": {
                            "type": "string"
                          },
                          "planName": {
                            "type": "string"
                          },
                          "planType": {
                            "type": "string",
                            "enum": [
                              "local",
                              "regional",
                              "global"
                            ]
                          },
                          "dataGb": {
                            "type": "number",
                            "nullable": true,
                            "description": "null when unlimited"
                          },
                          "dataLabel": {
                            "type": "string"
                          },
                          "isUnlimited": {
                            "type": "boolean"
                          },
                          "validityDays": {
                            "type": "integer"
                          },
                          "validityLabel": {
                            "type": "string"
                          },
                          "priceUsd": {
                            "type": "number",
                            "description": "List price in USD before coupons"
                          },
                          "priceValue": {
                            "type": "number",
                            "description": "Final coupon-applied price in the requested currency"
                          },
                          "formattedPrice": {
                            "type": "string"
                          },
                          "formattedOriginalPrice": {
                            "type": "string",
                            "nullable": true
                          },
                          "pricePerGbLabel": {
                            "type": "string",
                            "nullable": true
                          },
                          "hasCoupon": {
                            "type": "boolean"
                          },
                          "couponCode": {
                            "type": "string",
                            "nullable": true
                          },
                          "networkType": {
                            "type": "string"
                          },
                          "hotspotAllowed": {
                            "type": "boolean"
                          },
                          "hasFiveG": {
                            "type": "boolean"
                          },
                          "comboHref": {
                            "type": "string",
                            "description": "Site-relative comparison page for this country+provider"
                          },
                          "buyHref": {
                            "type": "string",
                            "description": "Site-relative tracked checkout redirect (/go/{id})"
                          }
                        },
                        "additionalProperties": true
                      }
                    },
                    "nextCursor": {
                      "type": "string",
                      "nullable": true
                    },
                    "totalMatching": {
                      "type": "integer"
                    },
                    "totalAll": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Unknown country slug"
          }
        }
      }
    },
    "/api/providers/{slug}/plans": {
      "get": {
        "operationId": "listProviderPlans",
        "summary": "Plans sold by a provider",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "saily",
            "description": "Provider slug. Directory: https://esimadvice.com/providers"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "maximum": 100,
              "default": 30
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "currency",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "example": "USD"
          }
        ],
        "responses": {
          "200": {
            "description": "Plan list (same item shape as country plans)"
          },
          "404": {
            "description": "Unknown provider slug"
          }
        }
      }
    },
    "/price-index.csv": {
      "get": {
        "operationId": "downloadPriceIndex",
        "summary": "Global eSIM Data Price Index (CSV, CC BY 4.0)",
        "description": "Every country ranked by real cheapest ≥1GB plan price, plus best price/GB, unlimited pricing, provider counts. Recomputed daily. Human version: https://esimadvice.com/price-index",
        "responses": {
          "200": {
            "description": "CSV download",
            "content": {
              "text/csv": {}
            }
          }
        }
      }
    }
  }
}