{
 "openapi": "3.1.0",
 "info": {
  "title": "go-v.org hub API",
  "version": "1.0.0",
  "description": "Key-free GET endpoints for cross-corpus search, the coverage register and one country record. Unreachable upstreams are reported, never replaced.",
  "contact": {
   "url": "https://go-v.org/docs"
  },
  "license": {
   "name": "Per corpus; see /datasets",
   "url": "https://go-v.org/datasets"
  }
 },
 "servers": [
  {
   "url": "https://go-v.org",
   "description": "Production"
  }
 ],
 "tags": [
  {
   "name": "search",
   "description": "Cross-corpus search"
  },
  {
   "name": "coverage",
   "description": "Rows held and coverage"
  },
  {
   "name": "country",
   "description": "One country record"
  }
 ],
 "paths": {
  "/api/v1/search": {
   "get": {
    "tags": [
     "search"
    ],
    "summary": "Search across the configured corpora",
    "operationId": "searchAll",
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "required": true,
      "description": "Search terms.",
      "schema": {
       "type": "string",
       "minLength": 1
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "Maximum fused results.",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 50,
       "default": 20
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Fused results plus per-source status.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SearchResponse"
        }
       }
      }
     },
     "429": {
      "$ref": "#/components/responses/RateLimited"
     }
    }
   }
  },
  "/api/v1/coverage": {
   "get": {
    "tags": [
     "coverage"
    ],
    "summary": "Rows held versus known universe",
    "operationId": "getCoverage",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Coverage register.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/CoverageResponse"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/country": {
   "get": {
    "tags": [
     "country"
    ],
    "summary": "One country record with lane coverage",
    "operationId": "getCountry",
    "parameters": [
     {
      "name": "iso2",
      "in": "query",
      "required": true,
      "description": "ISO 3166-1 alpha-2 country code.",
      "schema": {
       "type": "string",
       "pattern": "^[A-Za-z]{2}$"
      },
      "example": "KE"
     }
    ],
    "responses": {
     "200": {
      "description": "Country record.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/CountryRecord"
        }
       }
      }
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     }
    }
   }
  }
 },
 "components": {
  "responses": {
   "RateLimited": {
    "description": "Rate limit reached.",
    "headers": {
     "Retry-After": {
      "schema": {
       "type": "integer"
      }
     }
    },
    "content": {
     "application/json": {
      "schema": {
       "type": "object",
       "properties": {
        "error": {
         "type": "string"
        },
        "retry_after": {
         "type": "integer"
        }
       }
      }
     }
    }
   },
   "NotFound": {
    "description": "No such record.",
    "content": {
     "application/json": {
      "schema": {
       "type": "object",
       "properties": {
        "error": {
         "type": "string"
        }
       }
      }
     }
    }
   }
  },
  "schemas": {
   "SearchResponse": {
    "type": "object",
    "required": [
     "query_hash",
     "count",
     "results",
     "sources"
    ],
    "properties": {
     "query_hash": {
      "type": "string"
     },
     "count": {
      "type": "integer"
     },
     "results": {
      "type": "array",
      "items": {
       "type": "object",
       "required": [
        "source",
        "title",
        "url",
        "detail",
        "rrf"
       ],
       "properties": {
        "source": {
         "type": "string"
        },
        "title": {
         "type": "string"
        },
        "url": {
         "type": "string"
        },
        "detail": {
         "type": "string"
        },
        "rrf": {
         "type": "number"
        }
       }
      }
     },
     "sources": {
      "type": "array",
      "items": {
       "type": "object",
       "required": [
        "source",
        "ok",
        "count",
        "latency_ms"
       ],
       "properties": {
        "source": {
         "type": "string"
        },
        "ok": {
         "type": "boolean"
        },
        "count": {
         "type": "integer"
        },
        "latency_ms": {
         "type": "number"
        },
        "error": {
         "type": "string"
        }
       }
      }
     }
    }
   },
   "CoverageResponse": {
    "type": "object",
    "required": [
     "corpora",
     "generated_at"
    ],
    "properties": {
     "generated_at": {
      "type": "number"
     },
     "corpora": {
      "type": "array",
      "items": {
       "type": "object",
       "required": [
        "corpus",
        "service",
        "rows",
        "note"
       ],
       "properties": {
        "corpus": {
         "type": "string"
        },
        "service": {
         "type": "string"
        },
        "rows": {
         "type": [
          "integer",
          "null"
         ]
        },
        "universe": {
         "type": [
          "integer",
          "null"
         ]
        },
        "percent": {
         "type": [
          "number",
          "null"
         ]
        },
        "note": {
         "type": "string"
        }
       }
      }
     }
    }
   },
   "CountryRecord": {
    "type": "object",
    "required": [
     "identifier",
     "name",
     "coverage",
     "indicators"
    ],
    "properties": {
     "identifier": {
      "type": "string"
     },
     "iso3": {
      "type": "string"
     },
     "name": {
      "type": "string"
     },
     "region": {
      "type": "string"
     },
     "income_level": {
      "type": "string"
     },
     "capital": {
      "type": "string"
     },
     "labels": {
      "type": "object",
      "additionalProperties": {
       "type": "string"
      }
     },
     "indicators": {
      "type": "array",
      "items": {
       "type": "object",
       "properties": {
        "key": {
         "type": "string"
        },
        "value": {
         "type": [
          "number",
          "null"
         ]
        },
        "year": {
         "type": "string"
        },
        "source": {
         "type": "string"
        },
        "source_uri": {
         "type": "string"
        },
        "license": {
         "type": "string"
        }
       }
      }
     },
     "coverage": {
      "type": "array",
      "items": {
       "type": "object",
       "required": [
        "lane",
        "status",
        "note"
       ],
       "properties": {
        "lane": {
         "type": "string"
        },
        "status": {
         "type": "string"
        },
        "note": {
         "type": "string"
        },
        "source_url": {
         "type": "string"
        },
        "status_text": {
         "type": "string"
        }
       }
      }
     },
     "generated_at": {
      "type": "number"
     },
     "note": {
      "type": "string"
     },
     "indicator_count": {
      "type": "integer"
     }
    }
   }
  }
 }
}