# DatoQA: integration quickstart / guide d'intégration

Status: public pilot, partial coverage. No account, API key or wallet is required to read factual data.

Start here: https://datoqa.bhazarstudio.workers.dev/docs/quickstart — client configurations, three useful tasks and runnable examples. Use tools/list for the complete live MCP tool list.

## Connect an agent

Add a remote MCP server using Streamable HTTP:

URL: https://datoqa.bhazarstudio.workers.dev/mcp
Authentication: none

Copy the tested-protocol examples and client-specific configuration from /docs/quickstart; client configuration syntax varies. The server exposes catalog, list_sources, search_recalls, get_indicators, list_countries, get_record, get_evidence, get_exchange_rates, list_weather_locations get_weather, list_historical_indicators and get_historical_indicators. Tool responses provide structuredContent as well as JSON text. An MCP-compatible client still needs to be configured to use this server; publication does not automatically connect every agent.

1. Call catalog to inspect current coverage.
2. Call search_recalls with optional query (literal French text, up to 80 characters) and limit (1–20).
3. Read each returned item's data, citation, freshness and provenance. This response already contains the factual record; additional calls are optional.
4. Use get_evidence with an item id only when a source JSON snapshot is needed.

## Plain HTTP: one request for data and provenance

GET https://datoqa.bhazarstudio.workers.dev/v1/recalls?limit=3

Example JavaScript:

    const response = await fetch('https://datoqa.bhazarstudio.workers.dev/v1/recalls?limit=3');
    if (!response.ok) throw new Error('DatoQA unavailable');
    const result = await response.json();
    // Inspect result.status, result.coverage and each item's citation/freshness.

For a literal search, URL-encode q. Empty q returns the currently available sample. A successful HTTP status is not a claim that all data exists or is fresh.

## Interpret the result

- matches_in_partial_coverage: matches exist within the latest-20 sample only.
- no_match_in_partial_coverage: no match in that sample; never infer product safety.
- source_unavailable: no successful collection is available.
- source_stale: the collection has expired; refresh is required.

Snapshots are scheduled to refresh every six hours and expire after 24 hours without a successful refresh. Retrieval age is not the age of the underlying event. The original notice publication date is separate. Compare product references and lots against the official notice. Source/schema validation is not independent factual verification: independently_verified remains false. A SHA-256 digest proves integrity of the stored snapshot, not truth of the claim.

Recall coverage: France, latest 20 RappelConso notices. Source language: French. Historical search is available with scope=history and optional gtin/from/to/offset; inspect missing months and barcode indexing coverage. No global recall coverage, worldwide weather or independent safety certification. There is no uptime guarantee for this pilot.

## Public health, water, sanitation and education

Use get_historical_indicators or GET /v1/history?country=IND&indicator=basic_drinking_water&from=2000 with infant_mortality, basic_drinking_water, basic_sanitation or primary_completion. UN IGME, WHO/UNICEF JMP and UNESCO UIS series are distributed through World Bank WDI. Preserve source years, nulls and estimates. Infant mortality is per 1,000 live births, not percent. At least basic water/sanitation includes safely managed services but is not equivalent to that higher service category. Primary completion is a gross intake proxy that may exceed 100 percent; it does not track an individual cohort through graduation. Annual source updates and modeled revisions are not live measurements or independent verification. Use the directory for actual collected coverage.

## US monthly prices and employment

At the 2026-09-27 launch check, BLS was unavailable because upstream quota was exhausted. This is a supported interface, not a promise of available data; inspect /v1/us/economy/indicators first.

GET https://datoqa.bhazarstudio.workers.dev/v1/us/economy?indicator=unemployment&limit=12

MCP: list_us_economic_indicators and get_us_economic_indicators. Indicators: consumer_price_index (CPI-U, all items, U.S. city average, not seasonally adjusted, 1982-84=100), unemployment (seasonally adjusted CPS rate, civilian labor force 16+, percent), nonfarm_employment (seasonally adjusted CES total nonfarm payroll jobs in thousands). CPI is not a percent inflation rate and payroll employment is a level, not monthly job creation or a count of unique people. Default last 12 months; limit=1-120 or period=YYYY-MM, mutually exclusive. Current year and nine previous years: a rolling window, not a permanent archive. Source missing markers become null with original strings and notes retained; M13 annual averages are not months. Read preliminary/revision footnotes. Daily collection at 18:19 UTC; expire within 72h of retrieval or 100 days after the last numeric observation month-end. The BLS request supplies no publication timestamp. Cite BLS and the retrieval date. BLS.gov cannot vouch for the data or analyses derived from these data after the data have been retrieved from BLS.gov. Not independently verified.

## Central-bank policy rates

GET https://datoqa.bhazarstudio.workers.dev/v1/interest-rates?series=overnight_target
GET https://datoqa.bhazarstudio.workers.dev/v1/interest-rates?provider=boe&series=bank_rate&year=2020&format=csv

CSV exports: add format=csv to /v1/interest-rates, /v1/fx/history and /v1/history, or the corresponding existing MCP tools. HTTP downloads CSV; MCP returns export.content alongside the JSON observations. Original decimals where available, null flags, units, definitions, observation notes, source URL, expiry and evidence hashes are retained. A source-date gap or unavailable data keeps the explanatory JSON status. No implied forward fill or independent verification.

MCP: list_interest_rate_series and get_interest_rates. Use provider=boe and series=bank_rate for UK daily observations since 1975-01-02; original regime/precision notes retained, OGL attribution, no missing-date filling. Use provider=fed for eight US series: federal_funds_target (historical, research reconstruction before 1994), federal_funds_lower/upper, reserve_balances, excess_reserves/required_reserves (historical), primary_credit and overnight_reverse_repo. Start dates differ; inspect directory. No invented history, no effective market-rate substitution. Add provider=ecb for deposit_facility, main_refinancing (fixed tenders), marginal_lending, or historical main_refinancing_minimum_bid (2000–2008, not current). ECB data are sparse dates of changes since 1999, retrieved daily and expired after 72h; no daily filling. With default provider=boc, series is overnight_target or bank_rate. Default returns the latest published numeric observation; year=2020 returns one year, date=2020-03-27 an exact date, mutually exclusive. Unit: percent. History begins in 2010; missing cells remain null and missing dates are not filled. Dates belong to the daily series, not a decision announcement calendar: announcement and effective dates can differ. No retail borrowing rate, forecast or real-time quote. Refresh daily at 23:11 UTC; expire within 72h of retrieval or seven days after the latest numeric observation. Source: Bank of Canada, whose original data is available free at https://www.bankofcanada.ca/valet/docs/. DatoQA selects/groups the data and is not endorsed by the Bank. Source decimals, definitions and evidence are retained; independently_verified remains false.

## Current monthly and quarterly economics

GET https://datoqa.bhazarstudio.workers.dev/v1/economy?country=FR&indicator=inflation&limit=24&language=en

MCP: list_economic_indicators and get_economic_indicators. country is a Eurostat two-letter code (Greece = EL), unlike World Bank three-character codes. Supported keys: inflation (HICP total annual rate of change, monthly), unemployment (total age group/both sexes, seasonally adjusted, percent of active population, monthly), gdp_growth (real GDP chain-linked volume growth versus preceding quarter, calendar and seasonally adjusted). Data begins in 2020 and includes the latest published periods, not live estimates. Preserve source status flags, provisional observations and nulls. The last 24 periods are returned by default; limit can be 1–240. latest_available refers to the entire stored series and can precede the returned window. Refresh daily at 11:23 UTC, expire after 72 hours without successful retrieval. EU/EFTA scope is deliberate under Eurostat reuse terms. Eurostat is not responsible for DatoQA grouping or added labels. Original source snapshots and methodology links are included; no independent factual verification is claimed.

## Recent global earthquakes

GET https://datoqa.bhazarstudio.workers.dev/v1/earthquakes?min_magnitude=4&limit=20

MCP: get_earthquakes. Source: USGS M2.5+ past-week GeoJSON feed. Latest earthquakes first, up to 100, with magnitude type, longitude/latitude, depth in kilometres, origin time, source update time and contributing network. Reviewed is the source's review status, not a DatoQA independent check. Retrieval is hourly at minute 29 UTC; records expire within two hours of feed generation. This rolling feed is not an exhaustive earthquake history, an early-warning service or proof of safety when empty. Magnitudes and locations may be revised. Raw event evidence is deduplicated across identical refreshes; old evidence is retained after events leave the published window.

## Long annual historical series

GET https://datoqa.bhazarstudio.workers.dev/v1/history?country=USA&indicator=gdp_per_capita&from=1960&to=2025

New keys: renewable_energy (share of final energy consumption, not electricity mix), forest_area and agricultural_land (share of land), trade, exports and imports (percent of GDP, possibly above 100). These annual estimates may lag years; latest_available exposes the actual observation year. No missing value is interpolated.

Use /v1/history/indicators for twenty-two supported keys and /v1/countries for economy codes. One indicator per request keeps responses small. The full window starts in 1960 and ends at the last completed year; null years remain explicit. GDP in current dollars, constant 2015 dollars and per capita GDP answer different questions. No PPP conversion or pre-1960 reconstruction is implied. Cloudflare schedules up to two historical indicator imports per day, selecting missing or oldest series at least six days old, independently of the operator PC. The maximum retrieval age is 30 days. Original definitions, producers, source update dates and evidence are retained. This remains a single-publisher provenance check, not independent factual verification.

## US weather forecasts

GET https://datoqa.bhazarstudio.workers.dev/v1/weather?city=oklahoma-city

Use /v1/weather/locations or list_weather_locations for the ten city identifiers. get_weather returns NWS forecasts for the stated coordinates and grid point, not current observations, city-wide conditions or alerts. Celsius temperatures refer to individual day/night forecast periods. English source text and structured precipitation values are preserved without reconciling source rounding. Cite the source and retain each period's time zone. Retrieval is hourly; snapshots expire within two hours of retrieval or 24 hours of the source update, whichever is earlier. A failed city refresh never renews its old snapshot. These forecasts remain free during the pilot.

## International annual indicators

GET https://datoqa.bhazarstudio.workers.dev/v1/indicators?country=USA&indicator=population&language=en

MCP tool: get_indicators. Required country: a three-character World Bank code from list_countries or GET /v1/countries. Regional aggregates are excluded. Optional indicator: population, gdp or inflation (omit to receive all three). Display labels: en or fr. Source definitions remain in English.

Source: World Bank World Development Indicators. Five completed calendar years only; inspect record.data.period and each observation.year. Population is in persons, GDP in current US dollars (not inflation-adjusted or purchasing-power-adjusted), and consumer-price inflation is an annual percent. Values may be estimated or revised. Null means missing, never zero. latest_available is the latest non-null observation within our five-year window only. Read source definitions, original producers and footnotes before comparison.

The source is scheduled to refresh daily; cached records expire after seven days without a successful refresh. Annual data does not become current-year data because we fetched it today. Status can be source_unavailable, source_stale, available_in_scoped_coverage or partially_unavailable. The license is CC BY 4.0 as displayed on the three selected indicator pages. DatoQA groups the original observations and adds display labels; no independent verification or endorsement by the World Bank is claimed.

## ECB reference exchange rates

GET https://datoqa.bhazarstudio.workers.dev/v1/fx?currency=USD

MCP tool: get_exchange_rates, optional three-letter currency. Rates are quoted as units of currency per one EUR. Inspect observation_date; these are ECB working-day reference rates, not live or executable prices. Original decimal strings and source XML evidence are preserved. Daily refresh is scheduled at 16:37 UTC; records expire after 48 hours without collection or seven days after their source date, whichever comes first. ECB data is freely available at https://www.ecb.europa.eu/stats/policy_and_exchange_rates/euro_reference_exchange_rates/html/index.en.html . This endpoint is free. No independent verification is claimed.

## Historical daily exchange rates

GET https://datoqa.bhazarstudio.workers.dev/v1/fx/history?currency=USD&year=2008

GET https://datoqa.bhazarstudio.workers.dev/v1/fx/history?currency=USD&date=2008-09-15

MCP: list_exchange_rate_history and get_exchange_rate_history. The directory lists available years, currencies, observation counts, retrieval and expiry, and explicit gaps. One currency and one calendar year per request keep responses bounded; year and date are mutually exclusive. Units are currency per one EUR. Original decimal strings are preserved and N/A is null. No weekend carry-forward, interpolation, cross rates or redenomination. A historical series for a discontinued currency is not a current quote. Reference rates are not executable prices; original data is free at the cited ECB source. Three daily Cloudflare slots refresh the current year first, then missing/oldest years. Closed-year snapshots expire after 35 days; current-year snapshots within 48 hours or seven days after the latest archive observation.

## Official regional holidays

GET https://datoqa.bhazarstudio.workers.dev/v1/holidays?region=fr-metropole&year=2027

GET https://datoqa.bhazarstudio.workers.dev/v1/holidays?region=gb-england-and-wales&date=2026-12-28

MCP: list_holiday_regions and get_public_holidays. Consult the directory for available territories and years. One year (default current year) or one exact local civil date per call. Original titles and notes are preserved. International OpenHolidays entries include multilingual names, subdivisions, nationwide flags and half-day scope; distinguish source_kind=public_aggregator from government. Use nationwide_only=true for nationwide OpenHolidays entries; this never broadens a government calendar territory. OpenHolidays-derived data is ODbL 1.0; download the complete paginated collection at /v1/holidays/openholidays-export. Missing years are explicitly unavailable; no_holiday_listed_for_date never means a business is open, that the date is a working day, or that all local/sector rules were checked. These are not school calendars. Government calendars collected daily; OpenHolidays refresh rotates two countries hourly (20-hour minimum age), seven-day expiry. JSON sources provide no revision timestamp; retrieval is shown separately. No independent factual or legal verification is claimed.

## Pricing and privacy

Factual API and MCP tools remain free. For an optional ready-to-use annual country comparison, call MCP catalog with report_countries=["FRA","DEU","ESP","ITA","NLD"] on the general/economy connection, or GET /v1/paid/country-report?countries=FRA,DEU,ESP,ITA,NLD&preview=true&language=en. This FREE preview gives coverage, missing cells, definitions, price and an exact purchase_path; it does not reveal observations, sign or pay. Default: 1–10 countries, population/current-USD GDP/annual CPI inflation and five completed years. Custom historical selection: 1–6 of the 22 WDI indicators, 1–10 years from 1960 to the last completed year. HTTP indicators/from/to or MCP catalog report_indicators/report_from/report_to, supplied together. Energy, trade, water, health and education retain source definitions, actual observation years and interpretation notes. One payment of 0.002 USDC on Base includes aligned JSON rows, an embedded CSV export, original definitions/producers/notes and source snapshots. Original data is public and free; this pays for assembly and delivery, not exclusive data or independent factual verification. Any missing numeric cell, stale/incomplete evidence or mismatched source snapshot blocks purchase. Use purchase_path unchanged with an authorized x402 HTTP client; a changed snapshot returns 409 before payment and requires a new free preview. Ordinary MCP connectivity is not payment capability. Inspect /v1/payments/status. Do not blindly reauthorize after an ambiguous delivery timeout. Legacy ?country=USA&language=en remains supported with its original single-country response. The x402 v2 headers are PAYMENT-REQUIRED / PAYMENT-SIGNATURE / PAYMENT-RESPONSE. The separate /v1/testnet/paid-demo is synthetic and uses only Base Sepolia test USDC (0.001), never real factual data. Never send personal funds to test addresses.

Usage counters aggregate public HTTP routes, response status and timing. These counters store no query text, IP, wallet or request body. Platform logs are separate. No feedback call is required. See /v1/payments/status for the live payment configuration.

## En français

Connecter l'adresse MCP ci-dessus en HTTP distant, sans authentification. Les données factuelles sont gratuites. Une seule recherche renvoie déjà les fiches, leurs sources et leur fraîcheur. Les rappels se limitent aux 20 derniers rappels français : une absence de résultat ne prouve jamais qu'un produit est sûr. L'outil get_indicators fournit aussi la population, le PIB et l'inflation annuels pour les pays et territoires du catalogue mondial de la Banque mondiale sur cinq années terminées. Les libellés existent en français et anglais ; les définitions sources restent en anglais. Les sources sont contrôlées techniquement, sans contre-expertise indépendante. Des prévisions NWS sont proposées pour dix villes américaines. Le catalogue thématique /v1/topics présente aussi les taux BCE, vingt-deux historiques annuels depuis 1960, les statistiques mensuelles et trimestrielles Eurostat et les séismes récents USGS. Les dates de collecte et les périodes observées sont distinctes. Aucun wallet n'est nécessaire pour essayer le service.

## References

- Catalog: https://datoqa.bhazarstudio.workers.dev/catalog
- OpenAPI: https://datoqa.bhazarstudio.workers.dev/openapi.json
- Source dataset: https://data.economie.gouv.fr/explore/dataset/rappelconso-v2-gtin-espaces/
- Attribution: DGCCRF, DGAL, DGEC, DGPR; Licence Ouverte v2.0 (Etalab).

## MCP connection recovery

The four supported Streamable HTTP endpoints are /mcp, /mcp/fx, /mcp/economy and /mcp/holidays. Use their exact paths. Public MCP tools do not use OAuth, an API key or a wallet. A 404 on OAuth discovery does not mean the MCP data service is unavailable: configure authentication as none. Never send credentials from another service.

Use an official MCP client to construct protocol headers and metadata. Both generations are supported:
- Legacy 2024-11-05, 2025-03-26, 2025-06-18 and 2025-11-25: initialize, then notifications/initialized, then tools/list or tools/call. Use the protocol version returned by initialize in MCP-Protocol-Version. Do not wrap a legacy version in the modern per-request envelope.
- Modern 2026-07-28: server/discover is available; every request carries params._meta with io.modelcontextprotocol/protocolVersion and io.modelcontextprotocol/clientCapabilities (an object, even when empty). Include MCP-Protocol-Version and Mcp-Method matching the body, and Mcp-Name when required by the method, such as tools/call. Do not combine modern headers with a legacy initialize handshake. The official SDK constructs these fields; DatoQA does not guess missing client capabilities.

If the server reports unsupported_protocol, use a mutually supported version through the correct generation, rather than blindly resending the same request. For missing metadata or header mismatches, fix the indicated fields with the client SDK. Preserve the chosen endpoint/profile. DatoQA exposes tools and empty optional catalogs: resources/list, resources/templates/list and prompts/list return empty lists on every profile. There are no resource contents or prompts to retrieve; reads/gets and invalid cursors still fail. Use tools/list, then a listed tool with its input schema. A method-not-found response for an unknown method remains an error. Unknown tools and invalid arguments remain rejected.

Send Content-Type: application/json and accept application/json (legacy clients may also accept text/event-stream). Empty or broken JSON, oversized requests and explicitly excluded response types remain errors. Browser cross-origin requests are restricted; use a server-side MCP client or gateway. Do not disable Origin validation or forward an arbitrary browser Origin as a workaround.

For an optional ready-to-use country comparison, call catalog with report_countries on /mcp or /mcp/economy. This is a FREE preview, never a purchase. Check purchasable, coverage, freshness, price and purchase_path. A payment-capable HTTP client with explicit budget authorization must use that exact path; an unsigned HTTP 402 with PAYMENT-REQUIRED is the expected offer, not a server failure. Missing or stale data must not be purchased. JSON and CSV are included in the same purchase. Never automatically sign again after an ambiguous delivery timeout; reconcile the first attempt.