{
  "openapi": "3.0.1",
  "info": {
    "title": "Codes API",
    "version": "1.0.0",
    "description": "A REST lookup API for standard code lists, starting with **UN/LOCODE** — the United Nations Code for Trade and Transport Locations.\n\nEach code list is served from its own versioned path (`/v1/un-locode` today; further lists such as Basel and EWC codes will follow) and every endpoint answers a single question: *given a code, what are its details?*\n\nAll requests require an API key sent in the `x-api-key` header. Usage is throttled to 10 requests/second (burst 2).",
    "contact": {
      "name": "CIF Consulting",
      "url": "https://cif-consulting.co.uk"
    }
  },
  "servers": [
    {
      "url": "https://api.codes.cif-consulting.co.uk"
    }
  ],
  "tags": [
    {
      "name": "UN/LOCODE",
      "description": "United Nations Code for Trade and Transport Locations — a five-character code identifying ports, airports, rail and road terminals, and other locations involved in trade and transport worldwide. Data is sourced from the official UNECE dataset and refreshed twice a year (January and July)."
    }
  ],
  "paths": {
    "/v1/un-locode": {
      "get": {
        "tags": ["UN/LOCODE"],
        "operationId": "getUnLocode",
        "summary": "Look up a UN/LOCODE",
        "description": "Returns the details of a single UN/LOCODE location — country and location names, the code's parts, and coordinates where the source provides them.\n\nThe `code` parameter is case-insensitive: `DKAAR`, `dkaar`, and `DkAar` all return the same record.",
        "parameters": [
          {
            "name": "code",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "DKAAR",
            "description": "The full five-character UN/LOCODE: a two-letter ISO 3166-1 country code followed by a three-character location code, e.g. `DKAAR` (Aarhus, Denmark). Case-insensitive."
          }
        ],
        "security": [
          {
            "api_key": []
          }
        ],
        "responses": {
          "200": {
            "description": "The UN/LOCODE record.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnLocode"
                },
                "example": {
                  "Code": "DKAAR",
                  "CountryCode": "DK",
                  "LocationCode": "AAR",
                  "CountryName": "Denmark",
                  "LocationName": "Aarhus",
                  "LocationNameWoDiacritics": "Aarhus",
                  "UNLocode": "DKAAR",
                  "Latitude": 56.15,
                  "Longitude": 10.22
                }
              }
            }
          },
          "400": {
            "description": "Bad request — the `code` parameter is missing, or no record exists for the given code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "noCodeProvided": {
                    "summary": "The code query parameter is missing or empty",
                    "value": {
                      "errorType": "BadRequest",
                      "exceptionType": "Exception",
                      "message": "No code provided"
                    }
                  },
                  "noRecordForCode": {
                    "summary": "No record exists for the given code",
                    "value": {
                      "errorType": "BadRequest",
                      "exceptionType": "Exception",
                      "message": "No record for code"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the `x-api-key` header is missing or the key is not valid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Forbidden"
                },
                "example": {
                  "message": "Forbidden"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests — the usage plan throttle (10 requests/second, burst 2) was exceeded. Back off and retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Forbidden"
                },
                "example": {
                  "message": "Too Many Requests"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "UnLocode": {
        "type": "object",
        "title": "UnLocode",
        "description": "A single UN/LOCODE location record.",
        "properties": {
          "Code": {
            "type": "string",
            "description": "The full code as held in the list (identical to `UNLocode` for this list).",
            "example": "DKAAR"
          },
          "CountryCode": {
            "type": "string",
            "description": "ISO 3166-1 alpha-2 country code — the first two characters of the UN/LOCODE.",
            "example": "DK"
          },
          "LocationCode": {
            "type": "string",
            "description": "Three-character location identifier — the last three characters of the UN/LOCODE.",
            "example": "AAR"
          },
          "CountryName": {
            "type": "string",
            "description": "Full country name.",
            "example": "Denmark"
          },
          "LocationName": {
            "type": "string",
            "description": "Location name as provided by UNECE, including any diacritics.",
            "example": "Aarhus"
          },
          "LocationNameWoDiacritics": {
            "type": "string",
            "description": "Location name with diacritics stripped, as supplied by the source.",
            "example": "Aarhus"
          },
          "UNLocode": {
            "type": "string",
            "description": "The full five-character UN/LOCODE.",
            "example": "DKAAR"
          },
          "Latitude": {
            "type": "number",
            "nullable": true,
            "description": "Latitude in decimal degrees, parsed from the UNECE `DDMM[NS] DDDMM[EW]` coordinate field. `null` when the source value is blank or malformed.",
            "example": 56.15
          },
          "Longitude": {
            "type": "number",
            "nullable": true,
            "description": "Longitude in decimal degrees, parsed from the UNECE `DDMM[NS] DDDMM[EW]` coordinate field. `null` when the source value is blank or malformed.",
            "example": 10.22
          }
        }
      },
      "Error": {
        "type": "object",
        "title": "Error",
        "description": "Error envelope returned by the service for client and server errors.",
        "properties": {
          "errorType": {
            "type": "string",
            "description": "`BadRequest` for 400s, `InternalServerError` for 500s.",
            "example": "BadRequest"
          },
          "exceptionType": {
            "type": "string",
            "description": "Internal exception class name.",
            "example": "Exception"
          },
          "message": {
            "type": "string",
            "description": "Human-readable reason: `No code provided`, `No record for code`, or `Unknown list`.",
            "example": "No record for code"
          }
        }
      },
      "Forbidden": {
        "type": "object",
        "title": "GatewayMessage",
        "description": "Error shape returned directly by API Gateway (authentication and throttling).",
        "properties": {
          "message": {
            "type": "string",
            "example": "Forbidden"
          }
        }
      }
    },
    "securitySchemes": {
      "api_key": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "API key issued by CIF Consulting. Sent as the `x-api-key` request header."
      }
    }
  }
}