Docs / Open Data

Public Data API

Published API surface for platform stats, source coverage, score facts, company registry records, and verification nodes.

The Architect Public Data API

Purpose

QuantumQub publishes a public information surface so governments, companies, journalists, researchers, civic developers, and independent verification nodes can inspect platform stats, source coverage, score facts, registry records, and reproducibility metadata.

The API is not a claim that the platform is an oracle of truth. It is a published evidence layer: sources, timestamps, confidence, formulas, score inputs, missing-data gaps, and correction paths must be visible enough for outside parties to challenge or reproduce.

Base URL

https://quantumqub.com

Public Endpoints

GET /api/v2/open-data
GET /api/v2/stats
GET /api/v2/public-companies?country=GB&city=London&limit=25
GET /api/v2/geo/open-country-score?country=US&persist=0
GET /api/v2/scores/{subjectType}/{subjectId}
GET /api/v2/geo
POST /api/v2/public-companies/{id}/claim
POST /api/v2/public-companies/rectification
POST /api/v2/governance/claims

/api/v2/open-data

This is the discovery and publication endpoint. It returns:

  • API version and generated timestamp.
  • Public endpoint catalog.
  • Source catalog and registration requirements.
  • Platform entity counts.
  • Company registry coverage, claim counts, import runs, and public samples.
  • Score source coverage, fact coverage, and snapshot coverage.
  • Country score index from cached country scores.
  • Scientific limitations and node verification policy.
  • Route health for optional tables so consumers can detect partial coverage.

Example:

curl https://quantumqub.com/api/v2/open-data?limit=10

Scoring Publication Rules

  1. No source, no score.
  2. Missing metrics reduce confidence; missing metrics are never filled with fake neutral defaults.
  3. Every score must expose formula version, source URLs, metric years, confidence, stale-data status, and appeal or rectification path.
  4. Composite scores must keep pillar-level values visible so a strong pillar cannot hide a severe failure in another pillar.
  5. Cross-country ranking is only valid when source coverage, freshness, and methodology are comparable.

Verification Node Protocol

A verification node should not trust the application server blindly. It should:

  1. Fetch /api/v2/open-data for endpoint discovery and source catalog.
  2. Fetch /api/v2/geo/open-country-score?country={ISO2}&persist=0 for a fresh source-backed calculation.
  3. Fetch the upstream public source URLs returned in the metric payload.
  4. Canonicalize JSON payloads and calculate a SHA-256 source hash.
  5. Recompute metric normalization, pillar score, confidence, and total score.
  6. Compare the recomputed score with the published score and flag any drift above the published tolerance.
  7. Store a signed verification receipt containing endpoint URL, source URLs, source hash, formula version, calculated score, confidence, and timestamp.

Future on-chain anchoring should publish hashes of formulas, source snapshots, and score roots. Anchoring proves publication integrity; it does not prove real-world truth unless source and oracle validation remain open.

Launching A Verification Node

A minimal verification node can be launched without private credentials for the open country-score network:

  1. Poll GET /api/v2/open-data and cache api_version, source catalog, endpoint catalog, and route health.
  2. Select a country code from the country_score_index or /api/v2/geo.
  3. Fetch GET /api/v2/geo/open-country-score?country={ISO2}&persist=0 to obtain a fresh executable calculation without mutating the platform ledger.
  4. Fetch GET /api/v2/scores/country/{ISO2} to inspect the published formula, latest snapshot, source facts, and computed metric rows.
  5. Canonicalize the World Bank metric payloads by sorting object keys, preserving numeric values, and excluding transport-only timing fields when recomputing source hashes.
  6. Recompute the equation:
score = 0.30*EconomicVelocity + 0.30*SocietalWellness + 0.25*GeopoliticalStability + 0.15*ResourceAutonomy
confidence = available_registration_free_metrics / expected_registration_free_metrics * 100
  1. Compare recomputed score, confidence, pillar values, formula version, and inputs_hash against the published /api/v2/scores snapshot.
  2. Publish a signed receipt containing node id, endpoint URL, source URLs, source hash, formula version, calculated score, confidence, drift, and timestamp.
  3. For Picoflow/on-chain anchoring, publish only receipt/formula/source-root hashes. Do not publish private data or claim the chain proves real-world truth.

Operational node rule: if a metric is missing upstream, the node must keep it missing. It must not invent a neutral value to make countries look comparable.

Company Claim Data Rules

Public registry rows are not owner accounts. A company record can become a source-backed enterprise profile, but ownership remains pending until a KYC/eID verified claimant provides official owner or authority evidence and the evidence is approved.

Evidence examples:

  • Official registry officer URL.
  • Beneficial ownership filing.
  • Board resolution.
  • Notarized authorization.
  • Court or regulator document.
  • Uploaded proof_of_ownership document accepted by the verifier/reviewer workflow.

Source License Policy

QuantumQub preserves upstream attribution fields where available:

  • source_name
  • source_url
  • source_license
  • attribution
  • retrieved_at
  • last_seen_at
  • stale_after

Consumers must preserve these fields when republishing data. Some datasets are official public records; some are supplemental public graphs; some require provider keys. They are not legally or scientifically interchangeable.

Current Source Catalog

  • World Bank Open Data: no registration; country metrics.
  • SEC EDGAR: no registration; US public issuers and filings.
  • UK Companies House: public bulk products, API key for API access; UK registry records.
  • UN Population Data Portal: no registration; demographics planned for rollups.
  • UNDP Human Development Data: public downloads; HDI, education, health, and wellness reference metrics.
  • DBnomics: no registration; salary, CPI, OECD, IMF, Eurostat series planned where licensed.
  • FAOSTAT: no registration; food/agriculture/resource security planned.
  • Wikidata SPARQL: no registration; supplemental graph, not official owner proof.
  • DBpedia / Wikipedia Infobox Dumps: no registration; supplemental RDF/infobox corporate and institution facts, not official proof.
  • EU Open Data Portal: no registration for public datasets; EU statistics, registries, and public data where license permits.
  • Open Power System Data: no registration; energy production, consumption, and renewable mix metrics.
  • U.S. Energy Information Administration: use only public downloads as zero-registration; API-key access is provider-gated.
  • ACLED conflict data: useful for war/conflict/political-violence metrics, but access and licensing can vary, so include only public/legal exports.
  • PrismAPI: provider key required; optional enrichment, not part of the zero-registration source set.

Critical Limits

The platform must speak carefully:

  • It can be tamper-evident; it cannot honestly promise to be unhackable.
  • It can publish reproducible formulas; it cannot make political judgement disappear from weighting choices.
  • It can anchor hashes on-chain; it cannot make external public APIs impossible to manipulate.
  • It can score public institutions and companies; it must not become citizen surveillance.
  • It can become a source of information by publishing evidence, not by hiding uncertainty.