{
    "openapi": "3.0.1",
    "info": {
        "title": "BIC Facility Code Database",
        "description": "The BIC Facility Code Database contains a unique identifier for over 17,000 facilities in 160 countries",
        "termsOfService": "https://www.bic-code.org/api-terms-of-use/",
        "version": "2.0.1",
        "contact": {
            "name": "BIC API Support",
            "email": "bic@bic-code.org",
            "url": "https://www.bic-code.org/facility-codes/"
        }
    },
    "externalDocs": {
        "description": "Facility Code Documentation",
        "url": "https://github.com/bic-org/Facility-Code"
    },
    "servers": [
        {
            "url": "https://api.bic-code.org/v2",
            "description": "Production Environment"
        },
        {
            "url": "https://api.bic-code.org/uat-v2",
            "description": "UAT Environment"
        }
    ],
    "x-amazon-apigateway-gateway-responses": {
        "MISSING_AUTHENTICATION_TOKEN": {
            "statusCode": 404,
            "responseParameters": {
                "gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
            },
            "responseTemplates": {
                "application/json": "{\"status\":404,\"message\":\"Endpoint not found. See the documentation for the list of available endpoints.\",\"documentation\":\"https://docs.bic-code.org\",\"openapi\":\"https://docs.bic-code.org/bfc-api-v2.json\",\"support\":\"bic@bic-code.org\"}"
            }
        },
        "UNAUTHORIZED": {
            "statusCode": 401,
            "responseParameters": {
                "gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
            },
            "responseTemplates": {
                "application/json": "{\"status\":401,\"message\":\"Missing or invalid Authorization header. Use 'Authorization: Bearer <accessToken>' from POST /oauth/token.\",\"documentation\":\"https://docs.bic-code.org/guides/bic-facility-code/api#authentication\"}"
            }
        },
        "ACCESS_DENIED": {
            "statusCode": 403,
            "responseParameters": {
                "gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
            },
            "responseTemplates": {
                "application/json": "{\"status\":403,\"message\":\"You do not have permission to access this resource.\",\"documentation\":\"https://docs.bic-code.org/guides/bic-facility-code/api\"}"
            }
        },
        "DEFAULT_4XX": {
            "responseParameters": {
                "gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
            }
        },
        "DEFAULT_5XX": {
            "responseParameters": {
                "gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
            }
        }
    },
    "paths": {
        "/oauth/token": {
            "post": {
                "summary": "Authenticate - Collect a token for authentication",
                "tags": [
                    "Authentication"
                ],
                "security": [
                    {
                        "BasicAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful Request",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "accessToken": {
                                            "description": "A JWT used for Authorization",
                                            "type": "string",
                                            "example": "eyJhbGciOiJIUzI1Ni"
                                        },
                                        "access_token": {
                                            "description": "A JWT used for Authorization",
                                            "type": "string",
                                            "example": "eyJhbGciOiJIUzI1Ni"
                                        },
                                        "accessTokenExpiresAt": {
                                            "description": "UTC datetime for token expiry",
                                            "type": "string",
                                            "example": "2023-08-01T10:15:02.847559+00:00"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid Request",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "description": "Plain text explanation of issue",
                                            "type": "string",
                                            "example": "Invalid Authorization Header: Authorization Header Missing"
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/facilities": {
            "post": {
                "summary": "Create - Generate a Facility",
                "tags": [
                    "Add Facility"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/FacilityPost"
                            }
                        }
                    },
                    "required": true
                },
                "parameters": [
                    {
                        "name": "Safe-Generate-Mode",
                        "in": "header",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "enum": [
                                "true",
                                "false"
                            ],
                            "example": "false"
                        },
                        "description": "Optional header for safe generate mode."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful Post",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/FacilityPatch"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerAuth": []
                    }
                ]
            },
            "patch": {
                "summary": "Update - Change Facility Details",
                "tags": [
                    "Add Facility"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/FacilityPatch"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Successful Patch",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/FacilityPatch"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid Request",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "description": "Plain text explanation of issue",
                                            "type": "string",
                                            "example": "Facility code does not exist"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerAuth": []
                    }
                ]
            }
        },
        "/facilities/{code}": {
            "get": {
                "summary": "Code - Find A Facility by its Provider Code",
                "tags": [
                    "Find Facility"
                ],
                "parameters": [
                    {
                        "name": "code",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "example": "GBLIVJMDA"
                        }
                    },
                    {
                        "name": "codeProvider",
                        "in": "query",
                        "schema": {
                            "$ref": "#/components/schemas/CodeProvider"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "200 response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Facility"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerAuth": []
                    }
                ]
            }
        },
        "/facilities/byLocation/{unLocode}/{codeProvider}": {
            "get": {
                "summary": "UNLocode - Find Facilities By UNLocode and Code Provider",
                "description": "Returns facilities at the given UNLocode. By default the full result set is returned as an array; if it is too large for a single response, what fits is returned as the paged envelope with a 'nextToken'. Providing 'limit' (or 'nextToken') switches to paged responses: an object containing 'facilities' (up to 'limit' results, max 1000) and 'nextToken', an opaque token passed back on the next request to continue where the previous page ended ('nextToken' is null on the final page).",
                "tags": [
                    "Find Facility"
                ],
                "parameters": [
                    {
                        "name": "unLocode",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "codeProvider",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "description": "Maximum number of facilities per page (1-1000). Providing this switches to a paged response envelope.",
                        "schema": {
                            "type": "string",
                            "example": "100"
                        }
                    },
                    {
                        "name": "nextToken",
                        "in": "query",
                        "required": false,
                        "description": "Opaque pagination token returned by a previous paged response. Pass it back unchanged to retrieve the next page.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "200 response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/components/schemas/Facility"
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerAuth": []
                    }
                ]
            }
        },
        "/facilities/byCountry/{countryCode}/{codeProvider}": {
            "get": {
                "summary": "Country - Find Facilities By Country Code and Code Provider",
                "description": "Returns facilities in the given country. By default the full result set is returned as an array; if it is too large for a single response, what fits is returned as the paged envelope with a 'nextToken'. Providing 'limit' (or 'nextToken') switches to paged responses: an object containing 'facilities' (up to 'limit' results, max 1000) and 'nextToken', an opaque token passed back on the next request to continue where the previous page ended ('nextToken' is null on the final page).",
                "tags": [
                    "Find Facility"
                ],
                "parameters": [
                    {
                        "name": "countryCode",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "example": "GB"
                        }
                    },
                    {
                        "name": "codeProvider",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "example": "BIC"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "description": "Maximum number of facilities per page (1-1000). Providing this switches to a paged response envelope.",
                        "schema": {
                            "type": "string",
                            "example": "100"
                        }
                    },
                    {
                        "name": "nextToken",
                        "in": "query",
                        "required": false,
                        "description": "Opaque pagination token returned by a previous paged response. Pass it back unchanged to retrieve the next page.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "200 response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/components/schemas/Facility"
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerAuth": []
                    }
                ]
            }
        },
        "/facilities/byLastUpdated/{codeProvider}": {
            "get": {
                "summary": "Find Facilities Last Updated Within a Date Range",
                "description": "Returns facilities whose last updated datetime falls within the provided range. Both 'updatedAfter' and 'updatedBefore' must be provided and may be no more than six months apart; a wider range returns a validation error. Values may be an ISO 8601 date (YYYY-MM-DD) or datetime; a date-only 'updatedBefore' is inclusive of the whole day. Each returned facility includes a 'lastUpdated' datetime. By default the full result set is returned as an array; if it is too large for a single response, what fits is returned as the paged envelope with a 'nextToken'. Optionally pass 'geofenced=true' to return only facilities with a geofence, or 'geofenced=false' for only facilities without one. Providing 'limit' (or 'nextToken') switches to paged responses: an object containing 'facilities' (up to 'limit' results, max 1000) and 'nextToken', an opaque token passed back on the next request to continue where the previous page ended ('nextToken' is null on the final page).",
                "tags": [
                    "Find Facility"
                ],
                "parameters": [
                    {
                        "name": "codeProvider",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "example": "BIC"
                        }
                    },
                    {
                        "name": "updatedAfter",
                        "in": "query",
                        "required": true,
                        "description": "Start of the range, must be no more than six months before 'updatedBefore'",
                        "schema": {
                            "type": "string",
                            "example": "2024-01-01"
                        }
                    },
                    {
                        "name": "updatedBefore",
                        "in": "query",
                        "required": true,
                        "description": "End of the range, must be no more than six months after 'updatedAfter'",
                        "schema": {
                            "type": "string",
                            "example": "2024-06-30"
                        }
                    },
                    {
                        "name": "geofenced",
                        "in": "query",
                        "required": false,
                        "description": "When 'true' only facilities with a geofence are returned; when 'false' only facilities without one",
                        "schema": {
                            "type": "boolean",
                            "example": true
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "description": "Maximum number of facilities per page (1-1000). Providing this switches to a paged response envelope.",
                        "schema": {
                            "type": "string",
                            "example": "100"
                        }
                    },
                    {
                        "name": "nextToken",
                        "in": "query",
                        "required": false,
                        "description": "Opaque pagination token returned by a previous paged response. Pass it back unchanged to retrieve the next page.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "200 response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "allOf": [
                                            {
                                                "$ref": "#/components/schemas/Facility"
                                            },
                                            {
                                                "type": "object",
                                                "properties": {
                                                    "lastUpdated": {
                                                        "type": "string",
                                                        "format": "date-time",
                                                        "description": "The datetime the facility was last updated",
                                                        "example": "2024-03-15T10:30:00Z"
                                                    }
                                                }
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid Request",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "description": "Plain text explanation of issue",
                                            "type": "string",
                                            "example": "Date range between 'updatedAfter' and 'updatedBefore' must not exceed six months"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerAuth": []
                    }
                ]
            }
        },
        "/facilities/byName/{countryCode}": {
            "get": {
                "summary": "Name - Find Facilities By Country Code and Name",
                "description": "Returns facilities in the given country whose name contains the search term. By default the full result set is returned as an array; if it is too large for a single response, what fits is returned as the paged envelope with a 'nextToken'. Providing 'limit' (or 'nextToken') switches to paged responses: an object containing 'facilities' (up to 'limit' results, max 1000) and 'nextToken', an opaque token passed back on the next request to continue where the previous page ended ('nextToken' is null on the final page).",
                "tags": [
                    "Find Facility"
                ],
                "parameters": [
                    {
                        "name": "countryCode",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "example": "GB"
                        }
                    },
                    {
                        "name": "name",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "example": "ACME Limited"
                        }
                    },
                    {
                        "name": "codeProvider",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "example": "BIC"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "description": "Maximum number of facilities per page (1-1000). Providing this switches to a paged response envelope.",
                        "schema": {
                            "type": "string",
                            "example": "100"
                        }
                    },
                    {
                        "name": "nextToken",
                        "in": "query",
                        "required": false,
                        "description": "Opaque pagination token returned by a previous paged response. Pass it back unchanged to retrieve the next page.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "200 response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/components/schemas/Facility"
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerAuth": []
                    }
                ]
            }
        },
        "/facilities/nearby": {
            "get": {
                "summary": "Nearby - Find Facilities By Latitude and Longitude",
                "tags": [
                    "Find Facility"
                ],
                "parameters": [
                    {
                        "name": "longitude",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "number",
                            "example": 40.7128
                        }
                    },
                    {
                        "name": "latitude",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "number",
                            "example": -74.006
                        }
                    },
                    {
                        "name": "countryCode",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "$ref": "#/components/schemas/CountryCode"
                        }
                    },
                    {
                        "name": "radius",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "number",
                            "example": 1000
                        }
                    },
                    {
                        "name": "codeProvider",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "$ref": "#/components/schemas/CodeProvider"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "200 response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "type": "object",
                                        "properties": {
                                            "Facility": {
                                                "$ref": "#/components/schemas/Facility"
                                            },
                                            "distanceKilometers": {
                                                "type": "number",
                                                "format": "float",
                                                "description": "The Facility's Distance in kilometers from the point provided in the request"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid Request",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "description": "Plain text explanation of issue",
                                            "type": "string",
                                            "example": "Radius must be a valid number of metres."
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "BearerAuth": []
                    }
                ]
            }
        },
        "/facilities/geofence": {
            "get": {
                "summary": "Geofence - Use Latitude Longitude to determine if inside a Facility Geofence",
                "tags": [
                    "Find Facility"
                ],
                "parameters": [
                    {
                        "name": "longitude",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "number",
                            "example": 40.7128
                        }
                    },
                    {
                        "name": "latitude",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "number",
                            "example": -74.006
                        }
                    },
                    {
                        "name": "container_number",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "example": "BICU1234561"
                        }
                    }
                ],
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "200 response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "type": "object",
                                        "properties": {
                                            "Facility": {
                                                "$ref": "#/components/schemas/Facility"
                                            },
                                            "distanceKilometers": {
                                                "type": "number",
                                                "format": "float",
                                                "description": "The Facility's Distance in kilometers from the point provided in the request"
                                            },
                                            "inFacility": {
                                                "type": "boolean",
                                                "description": "A boolean value to indicate if point provided in request is inside the geofence"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/facilities/match": {
            "post": {
                "summary": "Match - Use Full Facility Details to find Facility",
                "tags": [
                    "Find Facility"
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/FacilityMatch"
                            }
                        }
                    },
                    "required": true
                },
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "200 response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "matches": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/Facility"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/facilities/search": {
            "get": {
                "summary": "Search - Use plain text in a Partial Search to find Facility",
                "tags": [
                    "Find Facility"
                ],
                "parameters": [
                    {
                        "name": "searchQuery",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "example": "Springfield Illinois 62704"
                        }
                    },
                    {
                        "name": "countryCode",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "$ref": "#/components/schemas/CountryCode"
                        }
                    },
                    {
                        "name": "codeProvider",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "$ref": "#/components/schemas/CodeProvider"
                        }
                    }
                ],
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "200 response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "allOf": [
                                            {
                                                "$ref": "#/components/schemas/Facility"
                                            },
                                            {
                                                "type": "object",
                                                "properties": {
                                                    "searchScore": {
                                                        "type": "number",
                                                        "format": "float",
                                                        "description": "A relevance score calculated by the search engine indicating how well this facility matches the search query. Higher scores indicate a better match for the specific query. The score is based on factors like term frequency and inverse document frequency, and is not a percentage or a fixed-range value; its magnitude is relative to other results for the same query."
                                                    }
                                                }
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/facilities/request": {
            "post": {
                "summary": "Change Request - Submit/amend an edit to an existing facility",
                "description": "Submit (or same-day amend) a change request for an existing facility: any mix of field changes, a proposed coordinate, and/or a proposed geofence (GeoJSON FeatureCollection). Requires the contributor group. Body: facilityCode, codeProvider, trustGrade, and at least one of fieldChanges / proposedCoordinate / geoJson.",
                "tags": [
                    "Change Requests"
                ],
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "description": "Change request payload",
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "201 created",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/facilities/request/new": {
            "post": {
                "summary": "Change Request - Propose a brand-new facility",
                "description": "Propose a new facility. Body: proposedFacility (POST /facilities shape, unLocode mandatory, no code), optional geoJson boundary, trustGrade, remarks. A candidate code is allocated and returned; it is NOT accepted until an approver confirms the request.",
                "tags": [
                    "Change Requests"
                ],
                "security": [
                    {
                        "BearerAuth": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "description": "Proposed facility payload",
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "201 created (candidateCode returned)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "FacilityCode": {
                "title": "Facility Code",
                "type": "string",
                "minLength": 8,
                "maxLength": 13,
                "example": "GBLIVJMDA"
            },
            "CodeProvider": {
                "title": "Code Provider",
                "type": "string",
                "enum": [
                    "BIC",
                    "SMDG"
                ],
                "example": "BIC"
            },
            "CountryCode": {
                "title": "Country Code",
                "description": "ISO 3166-1 alpha-2 country code",
                "type": "string",
                "maxLength": 2,
                "minLength": 2,
                "pattern": "^[A-Z]{2}$",
                "example": "GB"
            },
            "UnLocode": {
                "title": "UN/LOCODE",
                "type": "string",
                "maxLength": 5,
                "minLength": 5,
                "example": "GBLIV"
            },
            "Operator": {
                "title": "Operator",
                "type": "object",
                "properties": {
                    "name": {
                        "type": "string",
                        "example": "ACME Limited"
                    }
                },
                "required": [
                    "name"
                ]
            },
            "Address": {
                "type": "object",
                "title": "Address Details",
                "properties": {
                    "country": {
                        "title": "Country Name",
                        "type": "string",
                        "maxLength": 35,
                        "minLength": 1,
                        "example": "United States of America"
                    },
                    "city": {
                        "title": "City Name",
                        "type": "string",
                        "maxLength": 35,
                        "minLength": 1,
                        "example": "Springfield"
                    },
                    "street": {
                        "title": "Street Name",
                        "type": "string",
                        "maxLength": 70,
                        "example": "123 Main St"
                    },
                    "postcode": {
                        "title": "Post/Zip Code",
                        "type": "string",
                        "maxLength": 9,
                        "example": "62704"
                    },
                    "state": {
                        "title": "State or Equivalent Municipality",
                        "type": "string",
                        "maxLength": 35,
                        "example": "Illinois"
                    }
                }
            },
            "GeographicalCoordinate": {
                "type": "object",
                "properties": {
                    "latitude": {
                        "title": "Latitude Coordinate Value",
                        "type": "string",
                        "maxLength": 17,
                        "minLength": 1,
                        "example": "40.7128"
                    },
                    "longitude": {
                        "title": "Longitude Coordinate Value",
                        "type": "string",
                        "maxLength": 17,
                        "minLength": 1,
                        "example": "-74.0060"
                    }
                },
                "required": [
                    "latitude",
                    "longitude"
                ]
            },
            "GeographicalFeature": {
                "type": "object",
                "description": "When provided will always include a 'Polygon', may also include a centroid of the geofence is also provided as a 'Point'.",
                "properties": {
                    "type": {
                        "type": "string",
                        "enum": [
                            "FeatureCollection"
                        ]
                    },
                    "features": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Feature"
                        }
                    }
                }
            },
            "AlternativeUnLocode": {
                "type": "string",
                "example": "GBLIV"
            },
            "CodeListProviderCode": {
                "type": "string",
                "example": "JMDA"
            },
            "FacilityDetails": {
                "type": "object",
                "required": [
                    "name",
                    "address",
                    "geographicalCoordinate"
                ],
                "properties": {
                    "name": {
                        "title": "Facility Name",
                        "type": "string",
                        "maxLength": 70,
                        "minLength": 1,
                        "example": "ACME Limited"
                    },
                    "address": {
                        "$ref": "#/components/schemas/Address"
                    },
                    "formattedAddress": {
                        "title": "Formatted Address - A single line address for the facility from the structured address.",
                        "type": "string",
                        "example": "123 Main St, Springfield, Illinois, 62704, United States of America"
                    },
                    "geographicalCoordinate": {
                        "$ref": "#/components/schemas/GeographicalCoordinate"
                    },
                    "geographicalFeature": {
                        "$ref": "#/components/schemas/GeographicalFeature"
                    }
                }
            },
            "Facility": {
                "type": "object",
                "description": "Outlines the Facility, note if an 'aliasCode' is provided it indicates that a searched for code is deprecated in favour of the `code` see https://docs.bic-code.org/guides/bic-facility-code/alias-codes",
                "properties": {
                    "code": {
                        "$ref": "#/components/schemas/FacilityCode"
                    },
                    "aliasCode": {
                        "$ref": "#/components/schemas/FacilityCode"
                    },
                    "codeProvider": {
                        "$ref": "#/components/schemas/CodeProvider"
                    },
                    "countryCode": {
                        "$ref": "#/components/schemas/CountryCode"
                    },
                    "facilityManaged": {
                        "type": "boolean",
                        "description": "Indicates whether the facility is actively managed."
                    },
                    "unLocode": {
                        "$ref": "#/components/schemas/UnLocode"
                    },
                    "operator": {
                        "$ref": "#/components/schemas/Operator"
                    },
                    "facility": {
                        "$ref": "#/components/schemas/FacilityDetails"
                    },
                    "alternativeUnLocode": {
                        "$ref": "#/components/schemas/AlternativeUnLocode"
                    },
                    "codeListProviderCode": {
                        "$ref": "#/components/schemas/CodeListProviderCode"
                    }
                },
                "required": [
                    "code",
                    "codeProvider"
                ]
            },
            "FacilityPost": {
                "title": "Facility Post Schema",
                "required": [
                    "facility",
                    "operator",
                    "unLocode",
                    "codeProvider"
                ],
                "type": "object",
                "properties": {
                    "codeProvider": {
                        "$ref": "#/components/schemas/CodeProvider"
                    },
                    "unLocode": {
                        "$ref": "#/components/schemas/UnLocode"
                    },
                    "facility": {
                        "$ref": "#/components/schemas/FacilityDetails"
                    },
                    "operator": {
                        "$ref": "#/components/schemas/Operator"
                    }
                }
            },
            "FacilityPatch": {
                "title": "Facility Patch Schema",
                "type": "object",
                "required": [
                    "code",
                    "codeProvider"
                ],
                "properties": {
                    "code": {
                        "$ref": "#/components/schemas/FacilityCode"
                    },
                    "codeProvider": {
                        "$ref": "#/components/schemas/CodeProvider"
                    },
                    "facility": {
                        "$ref": "#/components/schemas/FacilityDetails"
                    },
                    "operator": {
                        "$ref": "#/components/schemas/Operator"
                    },
                    "codeRequested": {
                        "title": "Code Requested",
                        "type": "boolean",
                        "description": "Indicates whether a new facility code was requested and created (true) or an existing facility was matched and returned (false)",
                        "example": true
                    }
                }
            },
            "FacilityMatch": {
                "title": "Facility Post Schema",
                "type": "object",
                "properties": {
                    "code": {
                        "$ref": "#/components/schemas/FacilityCode"
                    },
                    "countryCode": {
                        "$ref": "#/components/schemas/CountryCode"
                    },
                    "codeProvider": {
                        "$ref": "#/components/schemas/CodeProvider"
                    },
                    "unLocode": {
                        "$ref": "#/components/schemas/UnLocode"
                    },
                    "facility": {
                        "$ref": "#/components/schemas/FacilityDetails"
                    },
                    "operator": {
                        "$ref": "#/components/schemas/Operator"
                    }
                },
                "example": {
                    "code": "GBLIVYULN",
                    "codeProvider": "BIC",
                    "countryCode": "GB",
                    "unLocode": "GBLIV",
                    "facility": {
                        "name": "ACME Limited",
                        "address": {
                            "street": "Saturn Business Park, School Lane",
                            "city": "Liverpool",
                            "state": "Merseyside",
                            "postcode": "L34 9GJ",
                            "country": "United Kingdom"
                        },
                        "geographicalCoordinate": {
                            "latitude": "53.461992",
                            "longitude": "-2.87132320000000"
                        }
                    },
                    "operator": {
                        "name": "ACME Limited"
                    }
                }
            },
            "Feature": {
                "description": "GeoJSon 'Feature' object",
                "externalDocs": {
                    "url": "https://tools.ietf.org/html/rfc7946#section-3.2"
                },
                "allOf": [
                    {
                        "type": "object",
                        "required": [
                            "geometry"
                        ],
                        "properties": {
                            "geometry": {
                                "oneOf": [
                                    {
                                        "description": "Polygon",
                                        "externalDocs": {
                                            "url": "https://tools.ietf.org/html/rfc7946#section-3.1.6"
                                        },
                                        "allOf": [
                                            {
                                                "type": "object",
                                                "required": [
                                                    "type",
                                                    "coordinates"
                                                ],
                                                "properties": {
                                                    "type": {
                                                        "type": "string",
                                                        "enum": [
                                                            "Polygon"
                                                        ]
                                                    },
                                                    "coordinates": {
                                                        "type": "array",
                                                        "items": {
                                                            "description": "A linear ring is a closed LineString with four or more positions. The first and last positions are equivalent, and they MUST contain identical values; their representation SHOULD also be identical. A linear ring is the boundary of a surface or the boundary of a hole in a surface. A linear ring MUST follow the right-hand rule with respect to the area it bounds, i.e., exterior rings are counterclockwise, and holes are clockwise.\n",
                                                            "externalDocs": {
                                                                "url": "https://tools.ietf.org/html/rfc7946#section-3.1.6"
                                                            },
                                                            "type": "array",
                                                            "items": {
                                                                "description": "GeoJSon fundamental geometry construct. A position is an array of numbers. There MUST be two or more elements. The first two elements are longitude and latitude, or easting and northing, precisely in that order and using decimal numbers. Altitude or elevation MAY be included as an optional third element. Implementations SHOULD NOT extend positions beyond three elements because the semantics of extra elements are unspecified and ambiguous. Historically, some implementations have used a fourth element to carry a linear referencing measure (sometimes denoted as \"M\") or a numerical timestamp, but in most situations a parser will not be able to properly interpret these values. The interpretation and meaning of additional elements is beyond the scope of this specification, and additional elements MAY be ignored by parsers.\n",
                                                                "externalDocs": {
                                                                    "url": "https://tools.ietf.org/html/rfc7946#section-3.1.1"
                                                                },
                                                                "type": "array",
                                                                "minItems": 2,
                                                                "maxItems": 3,
                                                                "items": {
                                                                    "type": "number"
                                                                }
                                                            },
                                                            "minItems": 4
                                                        }
                                                    }
                                                }
                                            }
                                        ]
                                    },
                                    {
                                        "description": "Point",
                                        "externalDocs": {
                                            "url": "https://tools.ietf.org/html/rfc7946#section-3.1.2"
                                        },
                                        "allOf": [
                                            {
                                                "type": "object",
                                                "required": [
                                                    "type",
                                                    "coordinates"
                                                ],
                                                "properties": {
                                                    "type": {
                                                        "type": "string",
                                                        "enum": [
                                                            "Point"
                                                        ]
                                                    },
                                                    "coordinates": {
                                                        "type": "array",
                                                        "minItems": 2,
                                                        "maxItems": 3,
                                                        "items": {
                                                            "type": "number"
                                                        },
                                                        "description": "A single position (longitude, latitude, and optional altitude)"
                                                    }
                                                }
                                            }
                                        ]
                                    }
                                ]
                            },
                            "properties": {
                                "$ref": "#/components/schemas/FeatureProperties"
                            }
                        }
                    }
                ]
            },
            "FeatureProperties": {
                "title": "Additional Metadata for GeoJson Feature",
                "type": "object",
                "properties": {
                    "trustGrade": {
                        "title": "Trust Grade",
                        "description": "The knowledge of which the geofence is based on",
                        "type": "string",
                        "enum": [
                            "FACILITY_PROVIDED",
                            "LOCAL_KNOWLEDGE",
                            "REVIEW_PANEL"
                        ],
                        "example": "REVIEW_PANEL"
                    },
                    "category": {
                        "title": "Feature Category",
                        "description": "At-least one feature must be 'FACILITY' if specifying categories, if no categories are specified the default is 'FACILITY'",
                        "type": "string",
                        "enum": [
                            "FACILITY",
                            "BERTH",
                            "TRUCK_QUEUE",
                            "GATE",
                            "ASSOCIATED_RAIL"
                        ],
                        "example": "FACILITY"
                    },
                    "remarks": {
                        "title": "General Remarks",
                        "description": "Additional information about the geofence",
                        "type": "string",
                        "example": "Facility X renamed to Facility Y"
                    }
                }
            },
            "TrustGrade": {
                "title": "Trust Grade",
                "description": "The provenance of the requested change, declared by the requester. Any trustGrade values inside submitted GeoJSON feature properties are ignored and replaced server-side with this value.",
                "type": "string",
                "enum": [
                    "FACILITY_PROVIDED",
                    "LOCAL_KNOWLEDGE",
                    "REVIEW_PANEL"
                ],
                "example": "LOCAL_KNOWLEDGE"
            },
            "FieldChange": {
                "title": "Field Change",
                "description": "One proposed text-field change. 'before' is the value as seen at submission time so reviewers can detect the record changing underneath the request.",
                "type": "object",
                "required": [
                    "field",
                    "after"
                ],
                "properties": {
                    "field": {
                        "type": "string",
                        "description": "The facility field being changed",
                        "enum": [
                            "name",
                            "street",
                            "city",
                            "state",
                            "postcode",
                            "country"
                        ],
                        "example": "city"
                    },
                    "label": {
                        "type": "string",
                        "description": "Optional display label for the field",
                        "example": "City"
                    },
                    "before": {
                        "type": "string",
                        "description": "The value as seen when the change was proposed",
                        "example": "Rotterdam"
                    },
                    "after": {
                        "type": "string",
                        "description": "The proposed new value",
                        "example": "Rotterdam-Zuid"
                    }
                }
            },
            "ChangeRequestPost": {
                "title": "Change Request Post Schema",
                "description": "A change request against an EXISTING facility. Must include at least one of fieldChanges, proposedCoordinate or geoJson. One request per facility per user per day: re-submitting the same day amends the earlier request in place.",
                "type": "object",
                "required": [
                    "facilityCode",
                    "codeProvider",
                    "trustGrade"
                ],
                "properties": {
                    "facilityCode": {
                        "$ref": "#/components/schemas/FacilityCode"
                    },
                    "codeProvider": {
                        "$ref": "#/components/schemas/CodeProvider"
                    },
                    "trustGrade": {
                        "$ref": "#/components/schemas/TrustGrade"
                    },
                    "remarks": {
                        "type": "string",
                        "maxLength": 150,
                        "description": "Optional free-text note shown to reviewers (sanitised, max 150 characters)",
                        "example": "Terminal was renamed in Q2 2026"
                    },
                    "fieldChanges": {
                        "type": "array",
                        "description": "Proposed name/address changes",
                        "items": {
                            "$ref": "#/components/schemas/FieldChange"
                        }
                    },
                    "proposedCoordinate": {
                        "type": "object",
                        "description": "Proposed new facility coordinate (WGS-84 decimal degrees)",
                        "required": [
                            "latitude",
                            "longitude"
                        ],
                        "properties": {
                            "latitude": {
                                "type": "number",
                                "example": 51.885
                            },
                            "longitude": {
                                "type": "number",
                                "example": 4.286
                            }
                        }
                    },
                    "geoJson": {
                        "description": "Proposed geofence as a GeoJSON FeatureCollection (Polygon features only; coordinates in [longitude, latitude] order)",
                        "allOf": [
                            {
                                "$ref": "#/components/schemas/GeographicalFeature"
                            }
                        ]
                    }
                }
            },
            "NewFacilityRequestPost": {
                "title": "New Facility Request Post Schema",
                "description": "A proposal for a brand-new facility. The proposedFacility uses the same shape as POST /facilities (unLocode is mandatory, no code is posted). A candidate facility code is allocated and returned immediately, but it is NOT an accepted code until a reviewer confirms the request.",
                "type": "object",
                "required": [
                    "proposedFacility",
                    "trustGrade"
                ],
                "properties": {
                    "proposedFacility": {
                        "$ref": "#/components/schemas/FacilityPost"
                    },
                    "geoJson": {
                        "description": "Proposed geofence as a GeoJSON FeatureCollection (may also be supplied as proposedFacility.facility.geographicalFeature)",
                        "allOf": [
                            {
                                "$ref": "#/components/schemas/GeographicalFeature"
                            }
                        ]
                    },
                    "trustGrade": {
                        "$ref": "#/components/schemas/TrustGrade"
                    },
                    "proposerRole": {
                        "type": "string",
                        "description": "Why the requester is proposing this facility: they are the facility owner/operator, or they act on the owner's behalf",
                        "enum": [
                            "OWNER",
                            "ON_BEHALF"
                        ],
                        "example": "OWNER"
                    },
                    "remarks": {
                        "type": "string",
                        "maxLength": 150,
                        "description": "Optional free-text note shown to reviewers (sanitised, max 150 characters)",
                        "example": "New barge terminal, opened Q2 2026"
                    }
                }
            }
        },
        "securitySchemes": {
            "BasicAuth": {
                "type": "http",
                "scheme": "basic",
                "description": "Used only on `POST /oauth/token` to exchange your `username:password` for a JWT. All other endpoints require Bearer authentication."
            },
            "BearerAuth": {
                "type": "http",
                "scheme": "bearer",
                "bearerFormat": "JWT",
                "description": "Required on every endpoint except `POST /oauth/token`. Use the `accessToken` returned by `/oauth/token` as `Authorization: Bearer <accessToken>`."
            }
        }
    }
}