{
  "openapi": "3.1.0",
  "info": {
    "title": "Citymirror Dataset Search API",
    "version": "0.1.0",
    "description": "Use this API when a user asks where to find datasets, open data, geospatial data, national statistics, sensor feeds, city data, or data sources for a specific place, city, region, country or digital-twin use case. Returns a data-availability map: source domains, availability and gaps.",
    "contact": {
      "name": "Data Corridor Limited",
      "url": "https://datacorridor.io"
    }
  },
  "servers": [
    {
      "url": "https://citymirror.io",
      "description": "Citymirror API"
    }
  ],
  "paths": {
    "/api/search": {
      "get": {
        "operationId": "searchDatasetSourcesGet",
        "summary": "Search for dataset source domains by place, city, country, topic and use case",
        "description": "Use this endpoint when a user asks where to find datasets, open data, geospatial data, national statistics, sensor feeds, city data, or data sources for a specific place, city, region, country or digital-twin use case.",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Natural-language dataset request"
          },
          {
            "name": "place",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "City or place name"
          },
          {
            "name": "country",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Country name or ISO code"
          },
          {
            "name": "topic",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "traffic",
                "air-quality",
                "population",
                "geospatial",
                "housing",
                "planning",
                "energy",
                "transport",
                "weather",
                "environment"
              ]
            },
            "description": "Dataset topic"
          },
          {
            "name": "use_case",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Use case, e.g. digital twin, urban planning"
          }
        ],
        "responses": {
          "200": {
            "description": "Data-availability map",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DataMap"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "searchDatasetSources",
        "summary": "Search for dataset source domains by natural-language intent",
        "description": "Use this endpoint when a user or AI agent asks where to find datasets, open data, geospatial data, national statistics, sensor feeds, or data sources for a place, city, region, country or use case (e.g. digital twin, smart city, urban planning). Returns source domains, availability summary and data gaps.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SearchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Data-availability map",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DataMap"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SearchRequest": {
        "type": "object",
        "required": [
          "query"
        ],
        "properties": {
          "query": {
            "type": "string",
            "description": "Natural-language dataset request, e.g. \"Find traffic datasets for Birmingham for digital twin modelling\""
          },
          "place": {
            "type": "string"
          },
          "country": {
            "type": "string"
          },
          "topic": {
            "type": "string",
            "enum": [
              "traffic",
              "air-quality",
              "population",
              "geospatial",
              "housing",
              "planning",
              "energy",
              "transport",
              "weather",
              "environment"
            ]
          },
          "use_case": {
            "type": "string"
          },
          "agent": {
            "type": "boolean"
          }
        }
      },
      "DataMap": {
        "type": "object",
        "properties": {
          "query_id": {
            "type": "string"
          },
          "interpreted_intent": {
            "type": "object"
          },
          "data_map": {
            "type": "object",
            "properties": {
              "coverage": {
                "type": "string"
              },
              "source_domains": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "domain": {
                      "type": "string"
                    },
                    "source_type": {
                      "type": "string"
                    },
                    "confidence": {
                      "type": "number"
                    }
                  }
                }
              },
              "missing_or_uncertain": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "next_actions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "citation_policy": {
            "type": "string"
          }
        }
      }
    }
  }
}