{
  "openapi": "3.1.0",
  "info": {
    "title": "Global Connect Hub public data API",
    "version": "1.0.0",
    "description": "Read-only access to Global Connect Hub's public business records with per-field source provenance, retrieval and verification timestamps, conflict retention and a change feed. GCH is not an official register; provenance is asserted at the individual record and field level.",
    "contact": {
      "url": "https://connecthubglobal.com/developers"
    }
  },
  "servers": [
    {
      "url": "https://connecthubglobal.com/api/v1"
    }
  ],
  "paths": {
    "/businesses": {
      "get": {
        "summary": "Search business records",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Free-text match on name, slug or description."
          },
          {
            "name": "country",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "industry",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "has_website",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "has_registration",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "listed",
            "in": "query",
            "schema": {
              "type": "boolean"
            },
            "description": "Only records with a stock ticker."
          },
          {
            "name": "updated_since",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 25,
              "maximum": 100
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching records."
          },
          "429": {
            "description": "Rate limited."
          }
        }
      }
    },
    "/businesses/{id}": {
      "get": {
        "summary": "One business record with field-level provenance",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Record UUID or record slug.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The record."
          },
          "404": {
            "description": "No such public record."
          }
        }
      }
    },
    "/businesses/{id}/sources": {
      "get": {
        "summary": "Evidence behind each claim, including disagreements",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Record UUID or record slug.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Claims grouped by field."
          }
        }
      }
    },
    "/businesses/{id}/regulatory": {
      "get": {
        "summary": "Register identifiers and cached official-register lookups",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Record UUID or record slug.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Identifiers plus cached register responses with their own timestamps."
          }
        }
      }
    },
    "/updates": {
      "get": {
        "summary": "Change feed",
        "parameters": [
          {
            "name": "since",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50,
              "maximum": 200
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Changes newest first, with previous and current values."
          }
        }
      }
    },
    "/industries": {
      "get": {
        "summary": "Industry facets with counts",
        "responses": {
          "200": {
            "description": "Facets."
          }
        }
      }
    },
    "/locations": {
      "get": {
        "summary": "Location facets with counts",
        "responses": {
          "200": {
            "description": "Facets."
          }
        }
      }
    },
    "/meta": {
      "get": {
        "summary": "Dataset coverage, confidence model, limits and limitations",
        "responses": {
          "200": {
            "description": "Metadata."
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "FieldProvenance": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "value": {
            "type": [
              "string",
              "null"
            ]
          },
          "confidence": {
            "type": "string",
            "enum": [
              "high",
              "medium",
              "low",
              "disputed",
              "unverified"
            ]
          },
          "disputed": {
            "type": "boolean"
          },
          "derived": {
            "type": "boolean",
            "description": "True when GCH worked the value out rather than reading it from a source."
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "source": {
                  "type": "string"
                },
                "source_url": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "method": {
                  "type": "string",
                  "enum": [
                    "official_register",
                    "first_party",
                    "aggregated",
                    "derived"
                  ]
                },
                "value": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "retrieved_at": {
                  "type": "string",
                  "format": "date-time"
                },
                "last_verified": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "format": "date-time"
                }
              }
            }
          }
        }
      }
    }
  }
}