{
  "openapi": "3.1.0",
  "info": {
    "title": "UKCS Data Atlas Public API",
    "version": "0.1.0",
    "description": "Preview public API for UKCS Data Atlas catalogue metadata, feature search, AOI open dataset search, source recency, attribution, and metocean capabilities."
  },
  "servers": [
    {
      "url": "https://api.ukcsdataatlas.com",
      "description": "Production API"
    }
  ],
  "paths": {
    "/api/catalogue": {
      "get": {
        "summary": "Get public dataset catalogue metadata",
        "operationId": "getCatalogue",
        "responses": {
          "200": {
            "description": "Catalogue, attribution, and recency metadata.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/search-features/summary": {
      "get": {
        "summary": "Get searchable feature counts",
        "operationId": "getFeatureSearchSummary",
        "responses": {
          "200": {
            "description": "Searchable feature summary.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchFeatureSummary"
                }
              }
            }
          }
        }
      }
    },
    "/api/search-features": {
      "get": {
        "summary": "Search named map features",
        "operationId": "searchFeatures",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 100
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 12
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching named features with centres and extents.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchFeaturesResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/search-open-datasets": {
      "get": {
        "summary": "Search open datasets around a point",
        "operationId": "searchOpenDatasetsPoint",
        "parameters": [
          {
            "name": "lat",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number",
              "minimum": -90,
              "maximum": 90
            }
          },
          {
            "name": "lon",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number",
              "minimum": -180,
              "maximum": 180
            }
          },
          {
            "name": "radius_m",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number",
              "minimum": 0,
              "maximum": 100000,
              "default": 5000
            }
          },
          {
            "name": "include",
            "in": "query",
            "required": false,
            "description": "Optional repeated theme or provider filter, for example include=seismic&include=geotechnical.",
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "style": "form",
            "explode": true
          },
          {
            "name": "limit_per_dataset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1000,
              "default": 250
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Grouped open dataset search results.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OpenDatasetSearchResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Search open datasets using a GeoJSON AOI",
        "operationId": "searchOpenDatasetsGeometry",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OpenDatasetSearchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Grouped open dataset search results.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OpenDatasetSearchResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/dataset-recency": {
      "get": {
        "summary": "Get source and tile-cache recency metadata",
        "operationId": "getDatasetRecency",
        "responses": {
          "200": {
            "description": "Dataset recency metadata.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/source-attributions": {
      "get": {
        "summary": "Get source attribution and licence metadata",
        "operationId": "getSourceAttributions",
        "responses": {
          "200": {
            "description": "Source attribution metadata.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/metocean/capabilities": {
      "get": {
        "summary": "Get modelled metocean provider capabilities",
        "operationId": "getMetoceanCapabilities",
        "responses": {
          "200": {
            "description": "Metocean provider and product capability metadata.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SearchFeatureSummary": {
        "type": "object",
        "properties": {
          "searchable_features": {
            "type": "integer"
          },
          "source_features": {
            "type": "integer"
          },
          "source_layers": {
            "type": "integer"
          }
        }
      },
      "SearchFeaturesResponse": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string"
          },
          "count": {
            "type": "integer"
          },
          "results": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "n": {
                  "type": "string",
                  "description": "Display name."
                },
                "t": {
                  "type": "string",
                  "description": "Display type or theme."
                },
                "l": {
                  "type": "string",
                  "description": "Source layer."
                },
                "x": {
                  "type": "number",
                  "description": "Centroid longitude."
                },
                "y": {
                  "type": "number",
                  "description": "Centroid latitude."
                },
                "x1": {
                  "type": "number"
                },
                "y1": {
                  "type": "number"
                },
                "x2": {
                  "type": "number"
                },
                "y2": {
                  "type": "number"
                },
                "provider": {
                  "type": "string"
                },
                "dataset": {
                  "type": "string"
                },
                "feature_count": {
                  "type": "integer"
                }
              }
            }
          }
        }
      },
      "OpenDatasetSearchRequest": {
        "type": "object",
        "required": [
          "geometry"
        ],
        "properties": {
          "geometry": {
            "description": "GeoJSON geometry in WGS84 longitude/latitude coordinates.",
            "$ref": "#/components/schemas/GeoJsonGeometry"
          },
          "radius_m": {
            "type": "number",
            "minimum": 0,
            "maximum": 100000,
            "default": 5000
          },
          "include": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Optional theme or provider filters."
          },
          "limit_per_dataset": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1000,
            "default": 250
          }
        }
      },
      "GeoJsonGeometry": {
        "type": "object",
        "required": [
          "type",
          "coordinates"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "Point",
              "LineString",
              "Polygon",
              "MultiPolygon"
            ]
          },
          "coordinates": {
            "type": "array"
          }
        }
      },
      "OpenDatasetSearchResponse": {
        "type": "object",
        "properties": {
          "summary": {
            "type": "object"
          },
          "tabs": {
            "type": "object"
          }
        }
      }
    }
  }
}