{
  "openapi": "3.1.0",
  "info": {
    "title": "eSIM Scout Japan API",
    "description": "API for comparing Japan eSIM plan listings. Purchase links are nullable and must only be used when purchase_status is provider_link. Prices and availability may change after the recorded data date.",
    "version": "1.3.0",
    "contact": {
      "name": "eSIM Scout Japan",
      "url": "https://esim.tangible-ghost.com"
    }
  },
  "servers": [
    {
      "url": "https://esim.tangible-ghost.com/api/v1",
      "description": "Production"
    }
  ],
  "paths": {
    "/plans": {
      "get": {
        "operationId": "searchPlans",
        "summary": "Search and filter Japan eSIM plans",
        "description": "Search Japan eSIM plan listings by data amount, duration, price, network type, and features. Results distinguish actionable provider links from listing-only reference data.",
        "parameters": [
          {
            "name": "data_min",
            "in": "query",
            "schema": { "type": "number" },
            "description": "Minimum data in GB"
          },
          {
            "name": "data_max",
            "in": "query",
            "schema": { "type": "number" },
            "description": "Maximum data in GB"
          },
          {
            "name": "unlimited",
            "in": "query",
            "schema": { "type": "boolean" },
            "description": "Filter for unlimited data plans only"
          },
          {
            "name": "duration_min",
            "in": "query",
            "schema": { "type": "integer" },
            "description": "Minimum duration in days"
          },
          {
            "name": "duration_max",
            "in": "query",
            "schema": { "type": "integer" },
            "description": "Maximum duration in days"
          },
          {
            "name": "price_max",
            "in": "query",
            "schema": { "type": "number" },
            "description": "Maximum price in USD"
          },
          {
            "name": "provider",
            "in": "query",
            "schema": { "type": "string" },
            "description": "Filter by provider ID"
          },
          {
            "name": "network",
            "in": "query",
            "schema": { "type": "string", "enum": ["4g", "5g"] },
            "description": "Filter by network type"
          },
          {
            "name": "voice",
            "in": "query",
            "schema": { "type": "boolean" },
            "description": "Require voice call support"
          },
          {
            "name": "sms",
            "in": "query",
            "schema": { "type": "boolean" },
            "description": "Require SMS support"
          },
          {
            "name": "hotspot",
            "in": "query",
            "schema": { "type": "boolean" },
            "description": "Require hotspot/tethering support"
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["price", "price_per_gb", "price_per_day", "data", "duration"],
              "default": "price"
            },
            "description": "Sort field"
          },
          {
            "name": "order",
            "in": "query",
            "schema": { "type": "string", "enum": ["asc", "desc"], "default": "asc" },
            "description": "Sort order"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": { "type": "integer", "default": 20, "maximum": 100 },
            "description": "Results per page"
          },
          {
            "name": "offset",
            "in": "query",
            "schema": { "type": "integer", "default": 0 },
            "description": "Pagination offset"
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated Japan eSIM plan listings with data dates and nullable purchase links.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "meta": {
                      "type": "object",
                      "properties": {
                        "total": { "type": "integer" },
                        "limit": { "type": "integer" },
                        "offset": { "type": "integer" },
                        "source": { "type": "string" },
                        "website": { "type": "string" },
                        "data_updated_at": { "type": ["string", "null"], "format": "date-time" },
                        "notice": { "type": "string" }
                      }
                    },
                    "plans": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": { "type": "string" },
                          "provider": {
                            "type": "object",
                            "properties": {
                              "id": { "type": "string" },
                              "name": { "type": "string" },
                              "rating": { "type": "number" }
                            }
                          },
                          "name": { "type": "string" },
                          "data": {
                            "type": "object",
                            "properties": {
                              "amount": { "type": "number" },
                              "unit": { "type": "string" },
                              "unlimited": { "type": "boolean" }
                            }
                          },
                          "duration": {
                            "type": "object",
                            "properties": {
                              "value": { "type": "integer" },
                              "unit": { "type": "string" }
                            }
                          },
                          "price": {
                            "type": "object",
                            "properties": {
                              "amount": { "type": "number" },
                              "currency": { "type": "string" },
                              "per_gb": { "type": "number" },
                              "per_day": { "type": "number" }
                            }
                          },
                          "network": { "type": "array", "items": { "type": "string" } },
                          "features": {
                            "type": "object",
                            "properties": {
                              "voice": { "type": "boolean" },
                              "sms": { "type": "boolean" },
                              "hotspot": { "type": "boolean" },
                              "top_up": { "type": "boolean" }
                            }
                          },
                          "purchase_status": {
                            "type": "string",
                            "enum": ["provider_link", "listing_only"]
                          },
                          "purchase_channel": {
                            "type": "string",
                            "enum": ["affiliate", "own", "directory"]
                          },
                          "purchase_url": {
                            "type": ["string", "null"],
                            "description": "Use only when purchase_status is provider_link"
                          },
                          "affiliate_url": {
                            "type": ["string", "null"],
                            "deprecated": true,
                            "description": "Compatibility alias for purchase_url"
                          },
                          "provider_url": { "type": "string" },
                          "source": {
                            "type": "object",
                            "required": ["type", "url", "retrieved_at", "price_locale"],
                            "properties": {
                              "type": {
                                "type": "string",
                                "enum": ["official_page", "partner_api", "first_party"]
                              },
                              "url": { "type": "string", "format": "uri" },
                              "retrieved_at": { "type": "string", "format": "date-time" },
                              "price_locale": { "type": "string" }
                            }
                          },
                          "data_updated_at": { "type": "string", "format": "date-time" },
                          "review_url": {
                            "type": "string",
                            "description": "In-depth provider review"
                          }
                        }
                      }
                    },
                    "related_articles": {
                      "type": "object",
                      "description": "Contextual article links"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/providers": {
      "get": {
        "operationId": "listProviders",
        "summary": "List all eSIM providers offering Japan plans",
        "description": "Returns all eSIM providers with Japan plans, including ratings, features, and plan counts.",
        "responses": {
          "200": {
            "description": "List of providers"
          }
        }
      }
    },
    "/recommend": {
      "get": {
        "operationId": "getRecommendations",
        "summary": "Get eSIM recommendations by travel style or scenario",
        "description": "Returns filtered planning results. Use 'category' for grouped listings, or 'days'/'usage'/'budget'/'trip_type' for scenario filtering. Results are not independent test endorsements.",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["best_value", "unlimited", "short_trip", "long_stay", "budget", "premium_5g"]
            },
            "description": "Filter by curated recommendation category"
          },
          {
            "name": "days",
            "in": "query",
            "schema": { "type": "integer" },
            "description": "Trip duration in days. Plans with sufficient duration are returned."
          },
          {
            "name": "usage",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["light", "moderate", "heavy", "nomad"]
            },
            "description": "Expected data usage level. light=1-3GB, moderate=3-5GB, heavy=10GB+, nomad=unlimited."
          },
          {
            "name": "budget",
            "in": "query",
            "schema": { "type": "number" },
            "description": "Maximum budget in USD."
          },
          {
            "name": "trip_type",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["short_trip", "long_stay", "budget", "unlimited", "family", "nomad"]
            },
            "description": "Travel style preset. short_trip=≤7 days, long_stay=14+ days, family=hotspot plans, nomad=unlimited data."
          }
        ],
        "responses": {
          "200": {
            "description": "Filtered plan listings with nullable purchase links. Returns 'plans' for scenario queries and 'recommendations' for category queries.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "meta": {
                      "type": "object",
                      "properties": {
                        "source": { "type": "string" },
                        "website": { "type": "string" },
                        "query": { "type": "object" },
                        "total": { "type": "integer" }
                      }
                    },
                    "plans": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": { "type": "string" },
                          "provider_name": { "type": "string" },
                          "name": { "type": "string" },
                          "data": { "type": "string", "description": "e.g. '5GB' or 'Unlimited'" },
                          "duration": { "type": "string", "description": "e.g. '30 days'" },
                          "price": { "type": "string", "description": "e.g. 'USD 16'" },
                          "price_per_gb": { "type": "number" },
                          "price_per_day": { "type": "number" },
                          "network": { "type": "array", "items": { "type": "string" } },
                          "carriers": { "type": "array", "items": { "type": "string" } },
                          "features": {
                            "type": "object",
                            "properties": {
                              "hotspot": { "type": "boolean" },
                              "voice": { "type": "boolean" },
                              "sms": { "type": "boolean" }
                            }
                          },
                          "purchase_status": {
                            "type": "string",
                            "enum": ["provider_link", "listing_only"]
                          },
                          "purchase_url": {
                            "type": ["string", "null"],
                            "description": "Use only when purchase_status is provider_link"
                          },
                          "affiliate_url": { "type": ["string", "null"], "deprecated": true },
                          "source": {
                            "type": "object",
                            "required": ["type", "url", "retrieved_at"],
                            "properties": {
                              "type": {
                                "type": "string",
                                "enum": ["official_page", "partner_api", "first_party"]
                              },
                              "url": { "type": "string", "format": "uri" },
                              "retrieved_at": { "type": "string", "format": "date-time" }
                            }
                          },
                          "review_url": {
                            "type": "string",
                            "description": "Link to provider review article"
                          }
                        }
                      }
                    },
                    "related_articles": {
                      "type": "object",
                      "description": "Contextual article links to share with users",
                      "properties": {
                        "speed_test": { "type": "string" },
                        "first_time_guide": { "type": "string" },
                        "pocket_wifi_comparison": { "type": "string" },
                        "setup_iphone": { "type": "string" },
                        "setup_android": { "type": "string" },
                        "compare_all": { "type": "string" }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/guide": {
      "get": {
        "operationId": "getGuide",
        "summary": "Get FAQ guides about eSIM and Japan connectivity",
        "description": "Returns structured FAQ guides for common eSIM questions. Designed for AI agents to answer user questions about eSIM setup, data usage, and Japan networks.",
        "parameters": [
          {
            "name": "topic",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "getting_started",
                "japan_networks",
                "how_much_data",
                "setup_iphone",
                "setup_android",
                "troubleshooting"
              ]
            },
            "description": "Guide topic. Omit to get all guides."
          }
        ],
        "responses": {
          "200": {
            "description": "FAQ guides with questions, answers, and related links"
          }
        }
      }
    }
  }
}