{
  "openapi": "3.1.0",
  "info": {
    "title": "Japan International Postage 2027 API",
    "version": "1.0.0",
    "description": "Japan Post raises international mail prices for items posted from February 1, 2027: a 500 g EMS to the US goes from ¥3,900 to ¥7,400, postcards from ¥100 to ¥140, and EMS switches to 1 kg weight bands. See the old and new price for your country and weight, and the cheapest way to send it.\n\nFree, no API key, CORS open. Fair use: about 120 requests per minute per IP. Also available as MCP tools at https://free-agent-tools.vercel.app/mcp"
  },
  "servers": [
    {
      "url": "https://japan-intl-postage.vercel.app"
    }
  ],
  "paths": {
    "/api/check": {
      "get": {
        "operationId": "japanInternationalPostageCheck",
        "summary": "How much does it cost to mail something from Japan abroad now, and after Japan Post's 2027-02-01 rate rise?",
        "description": "Japan Post revises its international mail rates for items posted from 2027-02-01 (press release 2026-10-09; Asahi reported about +37% on average). Give a destination (ISO code, English or Japanese country name) or zone 1–5 and a weight; get, for each service (EMS, air / SAL / surface parcel, small packet air, International Air Packet, standard letter, postcard), the current price (incl. the special surcharge on zone 3/4 EMS and air parcels), the revised price, the change in yen and %, which applies on your shipDate, the cheapest and cheapest tracked option before and after, the EMS weight-band shift (100 g bands up to 1 kg now → 1 kg bands), the 2027 parcel same-time discount, notes (SAL suspended, acceptance-status link) and a disclaimer. Deterministic, from Japan Post's published tables.\n\nExample: https://japan-intl-postage.vercel.app/api/check?destination=US&weightGrams=500",
        "parameters": [
          {
            "name": "destination",
            "in": "query",
            "required": false,
            "description": "Destination country: ISO code (US, GB, AU, CN…), English or Japanese name (アメリカ, 英国). Alternatively pass zone.",
            "schema": {
              "type": "string",
              "description": "Destination country: ISO code (US, GB, AU, CN…), English or Japanese name (アメリカ, 英国). Alternatively pass zone."
            }
          },
          {
            "name": "zone",
            "in": "query",
            "required": false,
            "description": "Japan Post zone (地帯) 1–5 if you have no country: 1 China/Korea/Taiwan, 2 other Asia, 3 Oceania/Canada/Mexico/Middle East/Europe, 4 USA incl. territories, 5 Central & South America/Africa.",
            "schema": {
              "type": "integer",
              "description": "Japan Post zone (地帯) 1–5 if you have no country: 1 China/Korea/Taiwan, 2 other Asia, 3 Oceania/Canada/Mexico/Middle East/Europe, 4 USA incl. territories, 5 Central & South America/Africa.",
              "minimum": 1,
              "maximum": 5
            }
          },
          {
            "name": "weightGrams",
            "in": "query",
            "required": false,
            "description": "Weight in grams incl. packaging (or weightKg). Rounded up to the next band. Not needed for service=postcard_air.",
            "schema": {
              "type": "number",
              "description": "Weight in grams incl. packaging (or weightKg). Rounded up to the next band. Not needed for service=postcard_air.",
              "minimum": 1,
              "maximum": 30000
            }
          },
          {
            "name": "weightKg",
            "in": "query",
            "required": false,
            "description": "Weight in kilograms (alternative to weightGrams).",
            "schema": {
              "type": "number",
              "description": "Weight in kilograms (alternative to weightGrams).",
              "minimum": 0.001,
              "maximum": 30
            }
          },
          {
            "name": "service",
            "in": "query",
            "required": false,
            "description": "Only quote one service (aliases: express, sal, surface, small_packet, air_packet, letter, postcard). Default: all that fit the weight.",
            "schema": {
              "type": "string",
              "description": "Only quote one service (aliases: express, sal, surface, small_packet, air_packet, letter, postcard). Default: all that fit the weight.",
              "enum": [
                "ems",
                "parcel_air",
                "parcel_sal",
                "parcel_surface",
                "small_packet_air",
                "airpacket",
                "letter_standard_air",
                "postcard_air"
              ]
            }
          },
          {
            "name": "shipDate",
            "in": "query",
            "required": false,
            "description": "YYYY-MM-DD you post it. Decides whether current (up to 2027-01-31) or revised rates apply. Default: today in Japan.",
            "schema": {
              "type": "string",
              "description": "YYYY-MM-DD you post it. Decides whether current (up to 2027-01-31) or revised rates apply. Default: today in Japan."
            }
          },
          {
            "name": "items",
            "in": "query",
            "required": false,
            "description": "Number of parcels posted together, for the 2027 same-time discount note (10–49: 10%, 50+: 13%).",
            "schema": {
              "type": "integer",
              "description": "Number of parcels posted together, for the 2027 same-time discount note (10–49: 10%, 50+: 13%).",
              "default": 1,
              "minimum": 1,
              "maximum": 10000
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Result as JSON. Always includes a `disclaimer` field.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid input. The body explains what to send and gives an example."
          },
          "429": {
            "description": "Too many requests from one IP. Retry after the Retry-After seconds."
          }
        }
      },
      "post": {
        "operationId": "japanInternationalPostageCheckPost",
        "summary": "How much does it cost to mail something from Japan abroad now, and after Japan Post's 2027-02-01 rate rise? (JSON body)",
        "description": "Japan Post revises its international mail rates for items posted from 2027-02-01 (press release 2026-10-09; Asahi reported about +37% on average). Give a destination (ISO code, English or Japanese country name) or zone 1–5 and a weight; get, for each service (EMS, air / SAL / surface parcel, small packet air, International Air Packet, standard letter, postcard), the current price (incl. the special surcharge on zone 3/4 EMS and air parcels), the revised price, the change in yen and %, which applies on your shipDate, the cheapest and cheapest tracked option before and after, the EMS weight-band shift (100 g bands up to 1 kg now → 1 kg bands), the 2027 parcel same-time discount, notes (SAL suspended, acceptance-status link) and a disclaimer. Deterministic, from Japan Post's published tables.",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [],
                "properties": {
                  "destination": {
                    "type": "string",
                    "description": "Destination country: ISO code (US, GB, AU, CN…), English or Japanese name (アメリカ, 英国). Alternatively pass zone."
                  },
                  "zone": {
                    "type": "integer",
                    "description": "Japan Post zone (地帯) 1–5 if you have no country: 1 China/Korea/Taiwan, 2 other Asia, 3 Oceania/Canada/Mexico/Middle East/Europe, 4 USA incl. territories, 5 Central & South America/Africa.",
                    "minimum": 1,
                    "maximum": 5
                  },
                  "weightGrams": {
                    "type": "number",
                    "description": "Weight in grams incl. packaging (or weightKg). Rounded up to the next band. Not needed for service=postcard_air.",
                    "minimum": 1,
                    "maximum": 30000
                  },
                  "weightKg": {
                    "type": "number",
                    "description": "Weight in kilograms (alternative to weightGrams).",
                    "minimum": 0.001,
                    "maximum": 30
                  },
                  "service": {
                    "type": "string",
                    "description": "Only quote one service (aliases: express, sal, surface, small_packet, air_packet, letter, postcard). Default: all that fit the weight.",
                    "enum": [
                      "ems",
                      "parcel_air",
                      "parcel_sal",
                      "parcel_surface",
                      "small_packet_air",
                      "airpacket",
                      "letter_standard_air",
                      "postcard_air"
                    ]
                  },
                  "shipDate": {
                    "type": "string",
                    "description": "YYYY-MM-DD you post it. Decides whether current (up to 2027-01-31) or revised rates apply. Default: today in Japan."
                  },
                  "items": {
                    "type": "integer",
                    "description": "Number of parcels posted together, for the 2027 same-time discount note (10–49: 10%, 50+: 13%).",
                    "default": 1,
                    "minimum": 1,
                    "maximum": 10000
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Result as JSON. Always includes a `disclaimer` field.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid input. The body explains what to send and gives an example."
          },
          "429": {
            "description": "Too many requests from one IP. Retry after the Retry-After seconds."
          }
        }
      }
    },
    "/api/rules": {
      "get": {
        "operationId": "japanInternationalPostageRules",
        "summary": "Japan Post international rate tables: current (to 2027-01-31) and revised (from 2027-02-01) for every service and zone, the country → zone list and service limits",
        "description": "Returns both full rate tables (rows of [maxWeightGrams, zone1..zone5] JPY), zones, countries, service limits, the SAL suspension note and 2027 extras, with sources and disclaimer. No inputs.",
        "responses": {
          "200": {
            "description": "Rules JSON with rulesAsOf and sources.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    }
  }
}