Verify a claimed figure against the official series

Returns verdict match | close | mismatch | cannot_verify with the official value, difference, diagnostics (wrong year, percent-vs-decimal, unit scaling), and the citation for the correct number.

get/v1/verify

Request

  • Base URL: https://statcite.com
  • URL: https://statcite.com/v1/verify
  • Auth: none declared

Query parameters

indicatorstring required

Registry key or explicit series id

countrystring
periodstring required

Usually a year, e.g. 2024

valuenumber

The claimed value Required unless claimed_value is sent instead. Send exactly one of value or claimed_value.

claimed_valuenumber

Alias of value, the name verify_claims and the verify_stat MCP tool use and the name this endpoint returns. Send exactly one of value or claimed_value.

tolerance_absnumber
tolerance_pctnumber
strict_sourceboolean

Never verify against a fallback source, and return an error instead. Without strict_source, a verify served from a transient-failure fallback returns cannot_verify, with the fallback value as indicative. A fallback for a series the primary source permanently lacks is judged normally, with disclosure.

as_ofstring

Historical IMF-vintage verification: judge the claim against the dated IMF WEO edition resolved from this date (e.g. '2019-04', '2019') instead of today's live data. Resolution uses a CONSERVATIVE month calendar (editions flip on 1 May and 1 November), not the IMF's exact release days. So a date late in a release month resolves to the previous edition even if the new one already existed. The response says so, and offers an exact-pinning escape hatch through get_series dated ids. It always verifies against a dated WEO edition, even for indicators whose live primary is World Bank WDI or the IMF Fiscal Monitor (see as_of.source_changed_for_as_of). Recent editions are served from the IMF's own dated vintage dataflows (api.imf.org) first, with DBnomics's dated editions as the deep archive, and the citation names which one served. Only the six WEO-dated registry indicators support it (gdp_growth, current_account_gdp, govt_debt_gdp, fiscal_balance_gdp, govt_revenue_gdp, govt_expenditure_gdp). Any other indicator is rejected with advice. Impossible calendar dates are rejected, never normalised.

Response

Verdict with citation

verdict'match' | 'close' | 'mismatch' | 'cannot_verify'
claimed_valuenumber
official_valuenumber nullable
is_projectionboolean

True when the matched official observation is an IMF WEO/Fiscal Monitor estimate/projection, not a final outturn. Kept for compatibility; observation_status carries the finer-grained classification.

observation_status'actual' | 'modeled_estimate' | 'estimate_or_actual' | 'projection' | 'unknown'

The honest status of the matched observation, as one of five values. 'actual' means a series StatCite classifies as outturn data (registry World Bank indicators not flagged as modelled, and explicit worldbank/ WDI ids), subject to routine revision. 'modeled_estimate' (added 1.4.1) means the registry flags the indicator as a modelled series, such as the World Bank's ILO-modelled unemployment and labour force participation estimates. That is a published figure, but a model output rather than a measured outturn. 'estimate_or_actual' means an IMF WEO/Fiscal Monitor observation before the projection boundary. The IMF's true latest-actual year varies by country and is not exposed by the data path, so recent values may be staff estimates, and this should never be read as a confirmed actual. 'projection' means at or after the heuristic boundary. 'unknown' means no observation matched the period, or the series is an explicit id outside StatCite's classification. Arbitrary DBnomics series can be forecast datasets, so consult the source.

status_method'horizon_heuristic' | 'as_published'

How observation_status was determined. 'horizon_heuristic' applies to IMF WEO/Fiscal Monitor series, where the boundary is derived from the response's own data: the payload's projection horizon on the DataMapper channel, and the dataset-code vintage year on the DBnomics channel. It is a heuristic, not IMF per-country metadata. 'as_published' applies otherwise.

periodstring
differencenumber nullable
relative_difference_pctnumber nullable
explanationstring
diagnosticsstring[]
seriesobject
countryobject
notesstring[]
fallback_usedboolean

Present and true when the official value came from a fallback source because the primary failed. A transient primary failure demotes the verdict to cannot_verify with the fallback value reported as indicative (a substitute source can differ by definition or vintage far beyond the verdict bands, and the primary may recover and serve a different number); when the primary permanently lacks the series/country, the fallback is the stable serving source and the verdict is judged normally with disclosure. Absent otherwise.

Changes

No recorded changes to this operation across all 1 revision of this API.