Official tourism statistics — OECD, Eurostat, UN Tourism via OWID, ISTAT, Banca d'Italia: country KPIs, time series, rankings, EU city tourism (Urban Audit), the Italy regional vulnerability index, side-by-side comparisons and Ask the Data (grounded, cited). Sources are never merged. Pro keys only.
pulse_kpiproread-only
PRO — Pulse headline KPIs for one country (ISO3): international arrivals, travel receipts (US$ and national currency), tourism share of GDP / employment, recovery vs 2019, receipts per arrival, nights year-to-date. Official statistics only (OECD, UN Tourism via OWID, Eurostat) — each KPI carries its own source, period, dataset code and a human `display` label; sources are never merged. Same data as GET /api/external/pulse/kpi/{iso3}.
| Parameter | Type / values | Description |
|---|
country* | string (3 chars) | ISO3 country code, e.g. ITA |
lang | en | it · default en | Language of the human `display`/`label` fields (default en) |
Returns kpis{}: kpis.<code>.value · period · yoy_pct · source_org · dataset_code · unit · display (Source — indicator · period) — plus country, country_label, sparklines
Try in Claude / Cursor: “Give me Italy's headline tourism KPIs (arrivals, receipts, GDP share) with source and year for each figure.”
pulse_seriesproread-only
PRO — Pulse time series for one curated indicator across up to 10 countries (ISO3) or EU NUTS2/NUTS3 region codes (ITC4, FR10, ES511 — v2). ~60 indicators: annual (intl_arrivals, travel_receipts_usd, tourism_gdp_share, capacity_bed_places, population, gdp_mio_eur…), monthly Eurostat (nights_total, nights_foreign, arrivals_monthly, platform_nights, occupancy_rate_bedrooms, hicp_accommodation…), Banca d'Italia (it_inbound_spend_by_origin…), ECB FX (fx_usd_per_eur, ref_area EUR). Points may carry a quality `status` (p provisional, e estimated, b break); series from lagged datasets carry `dataset_note`. One series per (source, country) — never merged; dimensional indicators (*_by_region, *_by_origin) return one series per region / origin country with a `breakdown` object (TOTAL is an explicit value, never a sum). Unknown indicator → error listing all valid codes. Without `from` the last 10 years are returned. Same data as GET /api/external/pulse/series.
| Parameter | Type / values | Description |
|---|
indicator* | string | Curated indicator code, e.g. nights_total, intl_arrivals, it_inbound_spend_by_origin |
countries* | array | ISO3 codes, e.g. ["ITA", "ESP"] — or NUTS2/NUTS3 region codes for regional indicators, e.g. ["ITC4", "FR10"]; "EUR" for ECB FX |
from | string (^\d{4}(-\d{2}(-\d{2})?|-Q[1-4])?$) | Start period, inclusive (YYYY, YYYY-MM, YYYY-MM-DD for daily series, or YYYY-Qn). Default: 10 years ago |
to | string (^\d{4}(-\d{2}(-\d{2})?|-Q[1-4])?$) | End period, inclusive (optional) |
source | string | Restrict to one source_org, e.g. OECD, EUROSTAT, UN_TOURISM_VIA_OWID, BANCA_D_ITALIA (optional) |
breakdown | array | Dimensional indicators only (*_by_region, *_by_origin): dimension value codes to keep, e.g. ["ITC2"] or ["TOTAL"]. Default: every value except TOTAL, one series each (breakdown.code/label/level) |
aggregates | boolean | Dimensional indicators: false = leaf values only (no macro-areas / world regions). Default true |
lang | en | it · default en | Language of the human `display`/`label` fields (default en) |
Returns series[]: ref_area · ref_area_label · source_org · dataset_code · unit · data_type · points[] (period, value, status?) · display · breakdown? (dimension value; accommodation_type ALL/HOTELLIKE/OTHER on ISTAT series) · series_break? ({period, reason, note, url} — ISTAT 2025 perimeter change on Italian nights/arrivals/capacity series: 2025+ not comparable with earlier years) — plus indicator, label, sources, default_source, freq, from, to, default_window_applied, dimension? · max 20 per call
Try in Claude / Cursor: “Compare monthly nights in tourist accommodation for Italy and Spain since 2023 (Eurostat) and describe the seasonality.”
pulse_rankingsproread-only
PRO — Pulse country rankings for one indicator. Default source UN Tourism via OWID (200+ economies); pass `source` for others (OECD; EUROSTAT for nights_total / arrivals_monthly — ranked on calendar-year totals). When the indicator has no series in the chosen source the error lists the available sources. Latest year per economy (6-year window) or a fixed `year`. Same data as GET /api/external/pulse/rankings.
| Parameter | Type / values | Description |
|---|
indicator | string · default intl_arrivals | Curated indicator code (default intl_arrivals) |
source | UN_TOURISM_VIA_OWID | OECD | EUROSTAT | BANCA_D_ITALIA · default UN_TOURISM_VIA_OWID | source_org (default UN_TOURISM_VIA_OWID) |
year | string (^\d{4}$) · default latest available per economy | Fixed year (default: latest available per economy) |
limit | integer 1–50 · default 20 | Rows (default 20) |
lang | en | it · default en | Language of the human `display`/`label` fields (default en) |
Returns rankings[]: rank · ref_area · ref_area_label · period · value · yoy_pct · cagr_5y · sparkline — plus indicator, label, source_org, year, economies, display, aggregation · max 20 per call
Try in Claude / Cursor: “Rank the top 15 countries by international arrivals (UN Tourism) and by nights in tourist accommodation (Eurostat).”
pulse_citiesproread-only
PRO — EU «busiest tourist cities» (Eurostat tour_occ_ninc + urb_cpop1, Urban Audit cities): total tourist nights, share by foreign visitors, nights per resident (with bucket: over_50 / 15_50 / 5_15 / 2_5 / under_2), latest population year per city. Top N by total nights; `country` (ISO2) adds that country's cities beyond the top N with their overall rank. Cities without the foreign split (e.g. Brussels) or population are excluded and counted. Same data as GET /api/external/pulse/cities and the Pulse «EU Cities» chart.
| Parameter | Type / values | Description |
|---|
year | string (^\d{4}$) · default latest with ≥30 cities | Reference year (default: latest with ≥30 cities) |
top | integer 5–100 · default 30 | Cities ranked by total nights (default 30) |
country | string (^[A-Za-z]{2}$) | ISO2 — also return this country's cities beyond the top N (e.g. IT) |
lang | en | it · default en | Language of the human `display`/`label` fields (default en) |
Returns rows[]: rank · city · name · country_iso3 · nights_total · nights_foreign · foreign_share_pct · population · population_year · nights_per_resident · bucket · greater_city — plus year, years, universe, country_rows[], excluded, sources, display · max 20 per call
Try in Claude / Cursor: “Which EU cities had the most tourist nights per resident in 2025, and how do the Italian cities rank?”
pulse_freshnessproread-only
PRO — Pulse warehouse freshness: version, build time, row counts and sync state per source (OECD, Eurostat, UN Tourism via OWID, ISTAT, Banca d'Italia) and next due sync. Same data as GET /api/external/pulse/freshness (without the internal operations block).
No parameters.
Returns warehouse + sources[]: warehouse.version · warehouse.built_at · warehouse.row_counts (per source) · warehouse.source_status · sources[] (source, cadence_days, last_success_at, next_due_at, warehouse_rows) · build · max 20 per call
Try in Claude / Cursor: “How fresh is the Pulse data warehouse — version, build time and rows per source?”
pulse_compareproread-only
PRO — Pulse side-by-side comparison of 2–6 countries (the data behind /pulse/compare): one row per indicator with ONE source per row (never merged), the most recent period shared by all countries, values + yoy, fresher points in latest_by_country and the last 10 points per country. Default indicators: intl_arrivals, travel_receipts_usd, nights_total (monthly → calendar-year totals). Same data as GET /api/external/pulse/compare.
| Parameter | Type / values | Description |
|---|
countries* | array | 2–6 ISO3 codes, e.g. ["ITA", "ESP", "FRA"] |
indicators | array · default intl_arrivals, travel_receipts_usd, nights_total | Curated indicator codes (default: intl_arrivals, travel_receipts_usd, nights_total) |
lang | en | it · default en | Language of the human `display`/`label` fields (default en) |
Returns rows[]: indicator · label · source_org · dataset_code · unit · period (latest shared) · values{ISO3: value, yoy_pct} · latest_by_country · missing · series{ISO3: last 10 points} · display — plus countries, country_labels, note · max 20 per call
Try in Claude / Cursor: “Compare Italy, Spain and France on international arrivals, receipts and nights — same source and year per row.”
pulse_italy_vulnerabilityproread-only
PRO — Italy regional tourism vulnerability index: composite 0–100 over the 20 regions (100 = most exposed), weighted mean of five min-max normalised components — tourism pressure (ISTAT nights per 1,000 residents and per km², 25), seasonality (Gini of monthly nights, 20), source-market concentration (HHI of foreign nights by country of residence, ISTAT, 20), air dependence (Assaeroporti passengers per 100 nights, 20), platform exposure (Eurostat platform nights per 100 nights, 15). Every component carries its raw values, period and sources; methodology.latest_period gives the freshest data per component. 2025 nights follow the ISTAT 2025 perimeter (series_break), homogeneous across regions → ranking valid. Same data as GET /api/external/pulse/italy/vulnerability.
| Parameter | Type / values | Description |
|---|
lang | en | it · default en | Language of the human `display`/`label` fields (default en) |
Returns regions[]: code (ITTER107) · label · composite (0-100) · rank · components_available · components{pressure, seasonality, concentration, air, platform}: {score, weight, label, detail} — plus year, ranked[], methodology{weights, normalisation, sources, latest_period, notes, series_break, break_affected} · max 20 per call
Try in Claude / Cursor: “Which Italian regions are most exposed to tourism shocks and why (pressure, seasonality, market concentration, air dependence, platforms)?”
pulse_askproread-only
PRO — Ask the Data: a grounded answer on official tourism statistics from the Pulse warehouse (OECD, Eurostat, UN Tourism via OWID, ISTAT, Banca d'Italia) — text-to-SQL + retrieval, every number cited. Use it for figures (arrivals, receipts, nights, spending by origin market, Italian regions); ask_tourismintel covers news only. Answers in the question's language. Pass `session_id` back for follow-ups. Quota: 15 questions/day per PRO key.
| Parameter | Type / values | Description |
|---|
question* | string | Your question (5-500 chars), English or Italian |
session_id | string | Conversation id returned by a previous call — keeps follow-up context (optional) |
lang | en | it | Language hint when the question is ambiguous (optional) |
Returns answer_markdown + citations[]: answer_markdown · citations (display = 'Source — indicator · period', audit = technical reference, sql) · chart_spec · session_id · quota (used / limit / reset_at) · max 20 per call
Try in Claude / Cursor: “Quali sono i primi mercati esteri per spesa turistica in Italia nell'ultimo anno disponibile? Cita le fonti.”
