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

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

## Connect an agent

Add a remote MCP server using Streamable HTTP:

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

Use your client's remote HTTP configuration; configuration file syntax varies between clients. 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. No complete historical archive, global recall coverage, worldwide weather or independent safety certification. There is no uptime guarantee for this pilot.

## Long historical series

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

Use /v1/history/indicators for twelve 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. A local PC collector refreshes up to two historical indicators per day when six days old, while the PC and Codex automation are running. 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.

## Pricing and privacy

Factual API and MCP tools are free. The separate GET /v1/testnet/paid-demo route is synthetic and accepts only Base Sepolia test USDC (0.001); it is not a paid factual-data product. A separate GET /v1/paid/country-report?country=USA&language=en bundles three annual series and their source snapshots for 0.002 USDC on Base (eip155:8453) when enabled; inspect /v1/payments/status first. It uses the x402 v2 PAYMENT-REQUIRED / PAYMENT-SIGNATURE / PAYMENT-RESPONSE headers. A complete fresh report is checked before payment is offered; unavailable or incomplete reports return 404/503 without settlement. Existing factual pilot tools remain free. A wallet-enabled HTTP client is required for this optional product; the MCP tools themselves remain free. 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. La météo n'est pas encore proposée. 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).