{
  "openapi": "3.1.1",
  "info": {
    "title": "Postcode.eu International Address API",
    "version": "1.0.0",
    "description": "This API provides international address autocomplete, validation, and address retrieval functionality. [Register an account](https://account.postcode.eu) to receive API credentials for free testing.",
    "contact": {
      "name": "Postcode.eu Contact",
      "url": "https://www.postcode.eu/contact"
    }
  },
  "externalDocs": {
    "description": "Postcode.eu documentation and demos",
    "url": "https://developer.postcode.eu/documentation"
  },
  "servers": [
    {
      "url": "https://api.postcode.eu"
    }
  ],
  "paths": {
    "/nl/v1/addresses/postcode/{postcode}/{houseNumber}/{houseNumberAddition}": {
      "get": {
        "summary": "Retrieve a Dutch address, based on the unique combination of postcode, house number and house number addition",
        "description": "Retrieve a Dutch address based on its unique combination of postcode, house number and house number addition. You must always check the houseNumberAddition result field, as a successful response is also returned if only the input addition isn't found.",
        "operationId": "nldAddress",
        "externalDocs": {
          "url": "https://developer.postcode.eu/documentation/nl/v1/Address/viewByPostcode"
        },
        "security": [
          {
            "basicAuth": []
          }
        ],
        "parameters": [
          {
            "name": "postcode",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[0-9]{4}\\s*[A-Za-z]{2}$",
              "examples": ["2012ES"]
            }
          },
          {
            "name": "houseNumber",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 99999,
              "examples": [30]
            }
          },
          {
            "name": "houseNumberAddition",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 0,
              "maxLength": 6,
              "examples": ["A 1", ""]
            },
            "description": "Addition to the house number, required to uniquely define an address with multiple additions. Always check the houseNumberAddition result field. A successful response is also returned if the input addition could not be matched. An empty string indicates the absence of an addition."
          }
        ],
        "responses": {
          "200": {
            "description": "Address data retrieved",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/cacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "street": {
                      "type": "string",
                      "maxLength": 80,
                      "description": "Street name in accordance with the BAG Registry (Dutch: BAG - Basisregistratie Adressen en Gebouwen). In capital and lowercase letters, including punctuation marks and accents. This field is at most 80 characters in length. Filled with \"Postbus\" in case it is a range of PO boxes."
                    },
                    "streetNen": {
                      "type": "string",
                      "maxLength": 24,
                      "description": "Street name in NEN-5825 notation, which has a lower maximum length. In capital and lowercase letters, including punctuation marks and accents. This field is at most 24 characters in length. Filled with \"Postbus\" in case it is a range of PO boxes."
                    },
                    "houseNumber": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 99999,
                      "description": "House number of a perceel. In case of a Postbus match the house number will always be 0"
                    },
                    "houseNumberAddition": {
                      "type": ["string", "null"],
                      "description": "Addition of the house number to uniquely define a location. These additions are officially recognized by the municipality. This field is at most 6 characters in length and null if the given addition was not found (see houseNumberAdditions result field). The addition \"\" is returned for an address without an addition."
                    },
                    "postcode": {
                      "type": "string",
                      "minLength": 6,
                      "maxLength": 6,
                      "description": "Four digit neighborhood code (first part of a postcode). Range: 1000-9999 plus two character letter combination (second part of a postcode). Range: \"AA\"-\"ZZ\""
                    },
                    "city": {
                      "type": "string",
                      "maxLength": 80,
                      "description": "Official city name in accordance with the BAG Registry (Dutch: BAG - Basisregistratie Adressen en Gebouwen). In capital and lowercase letters, including punctuation marks and accents. This field is at most 80 characters in length."
                    },
                    "cityShort": {
                      "type": "string",
                      "maxLength": 24,
                      "description": "City name, shortened to fit a lower maximum length. In capital and lowercase letters, including punctuation marks and accents. This field is at most 24 characters in length."
                    },
                    "cityId": {
                      "type": "string",
                      "description": "Unique identifier for the city (Dutch: woonplaatscode) as defined by the BAG Registry (Dutch: BAG - Basisregistratie Adressen en Gebouwen). Range \"0000\"-\"9999\""
                    },
                    "municipality": {
                      "type": "string",
                      "maxLength": 80,
                      "description": "Municipality name in accordance with the BAG Registry (Dutch: BAG - Basisregistratie Adressen en Gebouwen). In capital and lowercase letters, including punctuation marks and accents. This field is at most 80 characters in length. Examples: \"Baarle-Nassau\", \"'s-Gravenhage\", \"Haarlemmerliede en Spaarnwoude\"."
                    },
                    "municipalityShort": {
                      "type": "string",
                      "maxLength": 24,
                      "description": "Municipality name, shortened to fit a lower maximum length. In capital and lowercase letters, including punctuation marks and accents. This field is at most 24 characters in length. Examples: \"Baarle-Nassau\", \"'s-Gravenhage\", \"Haarlemmerliede c.a.\"."
                    },
                    "municipalityId": {
                      "type": "string",
                      "description": "Unique identifier for the municipality (Dutch: gemeentecode) as defined by the National Office for Identity Data (Dutch: Rijksdienst voor Indentiteitsgegevens (RvIG)). Range \"0000\"-\"9999\""
                    },
                    "province": {
                      "type": "string",
                      "description": "Official name of the province, correctly cased and with dashes where applicable."
                    },
                    "rdX": {
                      "type": ["integer", "null"],
                      "description": "X coordinate according to Dutch Coordinate system \"(EPSG) 28992 Amersfoort / RD New\" (Dutch: Rijksdriehoeksmeting). Values range from 0 to 300000 meters. Null for PO Boxes."
                    },
                    "rdY": {
                      "type": ["integer", "null"],
                      "description": "Y coordinate according to Dutch Coordinate system \"(EPSG) 28992 Amersfoort / RD New\" (Dutch: Rijksdriehoeksmeting). Values range from 0 to 300000 meters. Null for PO Boxes."
                    },
                    "latitude": {
                      "type": ["number", "null"],
                      "description": "Latitude of address. Null for PO Boxes."
                    },
                    "longitude": {
                      "type": ["number", "null"],
                      "description": "Longitude of address. Null for PO Boxes."
                    },
                    "bagNumberDesignationId": {
                      "type": ["string", "null"],
                      "description": "Unique identifier for address designation. (Dutch: Nummeraanduiding ID). Null for PO Boxes."
                    },
                    "bagAddressableObjectId": {
                      "type": ["string", "null"],
                      "description": "Unique identifier for addressable object designation (Dutch: Adresseerbaar object ID). If null no active object is currently registered."
                    },
                    "addressType": {
                      "type": "string",
                      "enum": [
                        "building",
                        "house boat site",
                        "mobile home site",
                        "PO box"
                      ],
                      "description": ""
                    },
                    "purposes": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "enum": [
                          "residency",
                          "assembly",
                          "detention",
                          "healthcare",
                          "industry",
                          "office",
                          "lodging",
                          "education",
                          "sport",
                          "shopping",
                          "other"
                        ]
                      },
                      "description": "List of all purposes (Dutch: gebruiksdoelen)."
                    },
                    "surfaceArea": {
                      "type": ["integer", "null"],
                      "description": "Surface in square meters. Null for PO Boxes."
                    },
                    "houseNumberAdditions": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "maxLength": 6
                      },
                      "description": "List of all house number additions having the postcode and houseNumber which was input. The addition \"\" is returned for an address without an addition."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Address not found"
          },
          "400": {
            "description": "Invalid input. For example, incorrect postcode or house number format."
          },
          "401": {
            "description": "Unauthorized"
          },
          "429": {
            "description": "Rate limit exceeded"
          }
        }
      }
    },
    "/international/v1/autocomplete/{context}/{term}/{language}/{buildingListMode}": {
      "get": {
        "summary": "Retrieve autocomplete suggestions based on input text and context",
        "description": "Returns suggestions for partial or full address input. The `context` parameter must start with a 3-letter ISO 3166-1 Alpha-3 country code (e.g. 'nld'). On drilldown, use the `value` from the selected match as the next `term`, and the `context` of the match as the new `context`.\n\n**Important**: Do not alter the `value` string. Spacing and casing must remain unchanged.",
        "operationId": "autocomplete",
        "externalDocs": {
          "url": "https://developer.postcode.eu/documentation/international/v1/Autocomplete/autocomplete"
        },
        "security": [
          {
            "basicAuth": []
          }
        ],
        "parameters": [
          {
            "name": "context",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "examples": ["nld", "deu"]
            }
          },
          {
            "name": "term",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "examples": ["Damrak 1", "2012ES 30"]
            }
          },
          {
            "name": "language",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "examples": ["nl-NL", "fr-FR"]
            }
          },
          {
            "name": "buildingListMode",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "short",
                "paged"
              ],
              "examples": ["paged"]
            }
          },
          {
            "$ref": "#/components/parameters/autocompleteSession"
          }
        ],
        "responses": {
          "200": {
            "description": "Autocomplete suggestions retrieved successfully",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/cacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "newContext": {
                      "type": ["string", "null"],
                      "description": "New context that is required for further autocomplete requests. Null if no context update is required."
                    },
                    "matches": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "value": {
                            "type": "string",
                            "description": "The value represents all matched address information. If the user selects this match the current term input must be replaced with this value."
                          },
                          "label": {
                            "type": "string",
                            "description": "Label describing this match. For example, a street or municipality name."
                          },
                          "description": {
                            "type": "string",
                            "description": "Additional information relevant to this match, helps with disambiguation between similar labels. For example, a postal code associated with a matched street."
                          },
                          "precision": {
                            "type": "string",
                            "enum": [
                              "None",
                              "Locality",
                              "PostalCode",
                              "Street",
                              "Address"
                            ],
                            "description": "Match precision, used to know what type of address information is available."
                          },
                          "context": {
                            "type": "string",
                            "description": "If the user selects this match, use this as the context parameter in subsequent autocomplete call. Contexts may expire and should not be stored."
                          },
                          "highlights": {
                            "type": "array",
                            "items": {
                              "type": "array",
                              "items": {
                                "type": "integer"
                              },
                              "minItems": 2,
                              "maxItems": 2
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Unauthorized"
          },
          "429": {
            "description": "Rate limit exceeded"
          }
        }
      }
    },
    "/international/v1/address/{context}/{dispatchCountry}": {
      "get": {
        "summary": "Retrieve full address details from an autocomplete context",
        "description": "Retrieves complete address details for a context with precision: `Address`. Requires a valid X-Autocomplete-Session header to track the session lifecycle.",
        "operationId": "address",
        "externalDocs": {
          "url": "https://developer.postcode.eu/documentation/international/v1/Autocomplete/getDetails"
        },
        "security": [
          {
            "basicAuth": []
          }
        ],
        "parameters": [
          {
            "name": "context",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "A context value from an autocomplete match with precision `Address`."
          },
          {
            "name": "dispatchCountry",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "examples": ["nld", ""]
            },
            "description": "Dispatching country ISO3 code, used to determine country address line presence. If not given, country is not added in mailLines."
          },
          {
            "$ref": "#/components/parameters/autocompleteSession"
          }
        ],
        "responses": {
          "200": {
            "description": "Address details retrieved",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/cacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "language": {
                      "$ref": "#/components/schemas/language"
                    },
                    "address": {
                      "$ref": "#/components/schemas/address"
                    },
                    "mailLines": {
                      "$ref": "#/components/schemas/mailLines"
                    },
                    "location": {
                      "$ref": "#/components/schemas/location"
                    },
                    "isPoBox": {
                      "$ref": "#/components/schemas/isPoBox"
                    },
                    "country": {
                      "$ref": "#/components/schemas/country"
                    },
                    "details": {
                      "$ref": "#/components/schemas/addressDetails"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input. Occurs when the input context does not have precision `Address`."
          },
          "401": {
            "description": "Unauthorized"
          },
          "429": {
            "description": "Rate limit exceeded"
          }
        }
      }
    },
    "/international/v1/validate/{country}": {
      "get": {
        "summary": "Validate a full address",
        "description": "Validates and corrects a full address from raw input fields. Returns match status, validation level, and optionally details for validated structures.",
        "operationId": "validate",
        "externalDocs": {
          "url": "https://developer.postcode.eu/documentation/international/v1/Validate/validate"
        },
        "security": [
          {
            "basicAuth": []
          }
        ],
        "parameters": [
          {
            "name": "country",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Country code (ISO 3166-1 Alpha-3), must be lower-case"
          },
          {
            "name": "postcode",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "The postcode"
          },
          {
            "name": "locality",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "The locality name"
          },
          {
            "name": "street",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "examples": ["Kerkweg"]
            },
            "description": "The street name, without building number or name"
          },
          {
            "name": "building",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "examples": ["4 A"]
            },
            "description": "The full building number, including any additions"
          },
          {
            "name": "region",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "The region name. Depending on the country this can be a province, a state or another type of administrative region. This is not typically needed to find matches, but can sometimes be useful to distinguish between otherwise similar matches."
          },
          {
            "name": "streetAndBuilding",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "examples": ["Kerkweg 4 A"]
            },
            "description": "The street name and building number. Use this parameter if you do not have separate street and building data. This parameter is not allowed in combination with the street or building parameter."
          }
        ],
        "responses": {
          "200": {
            "description": "Validation results with match details",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/cacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "country": {
                      "$ref": "#/components/schemas/country"
                    },
                    "matches": {
                      "description": "A list of matches to the input address. Matches are ordered from best to worst match to the input parameters. For use-cases without user interaction you typically only need to consider the top match.",
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "status": {
                            "type": "object",
                            "properties": {
                              "grade": {
                                "type": "string",
                                "enum": [
                                  "A",
                                  "B",
                                  "C",
                                  "D",
                                  "E",
                                  "F"
                                ],
                                "description": "Grade indicating how well the match corresponds to the input address: A - F, A indicating a perfect match, and F indicating an extremely poor match."
                              },
                              "validationLevel": {
                                "type": "string",
                                "enum": [
                                  "Building",
                                  "BuildingPartial",
                                  "Street",
                                  "Locality",
                                  "None"
                                ],
                                "description": "Indicates up to which address element the match is validated"
                              },
                              "isAmbiguous": {
                                "type": "boolean",
                                "description": "Indicates if this match is too similar in quality to other matches to be considered an unambiguous match to the input. This means there was not enough input data to decide between these matches."
                              }
                            }
                          },
                          "language": {
                            "$ref": "#/components/schemas/language"
                          },
                          "address": {
                            "$ref": "#/components/schemas/address"
                          },
                          "mailLines": {
                            "$ref": "#/components/schemas/mailLines"
                          },
                          "location": {
                            "$ref": "#/components/schemas/location"
                          },
                          "isPoBox": {
                            "$ref": "#/components/schemas/isPoBox"
                          },
                          "country": {
                            "$ref": "#/components/schemas/country"
                          },
                          "details": {
                            "$ref": "#/components/schemas/addressDetails"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input parameters"
          },
          "401": {
            "description": "Unauthorized"
          },
          "429": {
            "description": "Rate limit exceeded"
          }
        }
      }
    },
    "/international/v1/country/{country}": {
      "get": {
        "summary": "Resolve a country name or code to ISO information",
        "description": "Returns ISO country codes for a given country name or input code. If no match is found, returns a 404 with null body.",
        "operationId": "country",
        "externalDocs": {
          "url": "https://developer.postcode.eu/documentation/international/v1/Validate/getCountry"
        },
        "security": [
          {
            "basicAuth": []
          }
        ],
        "parameters": [
          {
            "name": "country",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "A country name, or ISO code"
          }
        ],
        "responses": {
          "200": {
            "description": "Country matched",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/cacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/country"
                }
              }
            }
          },
          "404": {
            "description": "No match found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "null"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Unauthorized"
          },
          "429": {
            "description": "Rate limit exceeded"
          }
        }
      }
    },
    "/international/v1/supported-countries": {
      "get": {
        "summary": "List all supported countries",
        "description": "Returns all countries currently supported by the international APIs. Use the Cache-Control response header to determine how long to cache this list. **This list changes infrequently and should always be cached**.",
        "operationId": "supportedCountries",
        "externalDocs": {
          "url": "https://developer.postcode.eu/documentation/international/v1/Autocomplete/getSupportedCountries"
        },
        "security": [
          {
            "basicAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "List of supported countries",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/cacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/country"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "429": {
            "description": "Rate limit exceeded"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "basicAuth": {
        "type": "http",
        "scheme": "basic"
      }
    },
    "schemas": {
      "country": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "The country name in English"
          },
          "iso3": {
            "type": "string",
            "minLength": 3,
            "maxLength": 3,
            "description": "The ISO 3166-1 Alpha-3 code for the country. Use as the initial context parameter for the autocomplete method."
          },
          "iso2": {
            "type": "string",
            "minLength": 2,
            "maxLength": 2,
            "description": "The ISO 3166-1 Alpha-2 code for the country"
          }
        }
      },
      "language": {
        "type": "string",
        "description": "Language code for the language used in the results"
      },
      "address": {
        "type": "object",
        "properties": {
          "country": {
            "type": "string",
            "description": "Country name of the of postal address in English"
          },
          "locality": {
            "type": ["string", "null"],
            "description": "Name of primary locality used in postal address"
          },
          "street": {
            "type": ["string", "null"],
            "description": "Name of primary street used in postal address"
          },
          "postcode": {
            "type": ["string", "null"],
            "description": "Postcode used in postal address"
          },
          "building": {
            "type": ["string", "null"],
            "description": "The formatted building number of the postal address, including possible additions for the location. (United Kingdom: multiple lines are comma separated)"
          },
          "buildingNumber": {
            "type": ["integer", "null"],
            "description": "Building number of the postal address, or null if not available."
          },
          "buildingNumberAddition": {
            "type": ["string", "null"],
            "description": "Building number addition of the postal address, if available. (United Kingdom: multiple lines are comma separated)"
          },
          "region": {
            "type": ["string", "null"],
            "description": "The region the address resides in. Depending on the country this can be a province, a state or another type of administrative region."
          }
        }
      },
      "mailLines": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "Postal mail lines as used to address letters or packages to the address"
      },
      "location": {
        "type": [
          "object",
          "null"
        ],
        "properties": {
          "latitude": {
            "type": "number",
            "format": "double"
          },
          "longitude": {
            "type": "number",
            "format": "double"
          },
          "precision": {
            "type": "string",
            "enum": [
              "Address",
              "Street",
              "PostalCode",
              "Locality"
            ],
            "description": "Precision of location"
          }
        },
        "description": "WGS-84 coordinates for the address if available, null otherwise"
      },
      "isPoBox": {
        "type": "boolean",
        "description": "Indicates if the address is a Post Office box"
      },
      "addressDetails": {
        "type": ["object", "null"],
        "additionalProperties": true,
        "description": "Country specific details about the address, if available. The available details differ per country but can contain such things as country specific identifiers, official street name translations, administrative regions and an indication whether the full house number could be validated."
      }
    },
    "headers": {
      "cacheControl": {
        "description": "Indicates how long the result may be cached",
        "schema": {
          "type": "string",
          "examples": ["public, max-age=28800"]
        }
     }
    },
    "parameters": {
      "autocompleteSession": {
        "name": "X-Autocomplete-Session",
        "in": "header",
        "required": true,
        "description": "An identifier for a single address entry session (i.e., a user filling out a single address). You should not generate a new session identifier for each request, or reuse the same identifier for completing more than one address.",
        "schema": {
          "type": "string",
          "pattern": "^[A-Za-z0-9._-]{8,64}$",
          "examples": ["session-8349223902"]
        }
      }
    }
  }
}