Search data.gov.rs datasets. ALWAYS call this first — never guess dataset IDs.

Returns dataset IDs needed for get_dataset(). Serbian and English both work (e.g. 'stanovništvo' or 'population', 'budžet' or 'budget').

Returns: {datasets: [{id, title, organization, resources, tags, ...}], total, page, page_size, has_next}

List publishers on data.gov.rs. Use returned IDs to filter search_datasets().

Key orgs: РЗС (statistics), Министарство финансија (budget), Завод за јавно здравље (health).

Returns: {organizations: [{id, name, description, url, logo}], count, page, page_size}

Autocomplete dataset titles. Use when unsure of exact Serbian terms.

Example: suggest_datasets("stanov") → ["Stanovništvo Republike Srbije", ...]

Find all datasets tagged with specific topics regardless of publisher.

Common tags: "statistika", "budžet", "obrazovanje", "zdravlje", "saobraćaj", "cene", "registar", "ekologija", "stanovništvo".

Returns: Same shape as search_datasets().

Get dataset and organization counts for the portal overview.

Search datasets with semantic understanding and fallback suggestions (RECOMMENDED).

Uses the cached local catalog for fast results without API rate limits. Expands queries with synonyms and Serbian↔English translations, and offers related-dataset suggestions when no exact match is found.

Prefer this over search_datasets() unless you need live API results or organization/format filters.

Show dataset metadata with a data preview (first N rows) before downloading.

Use this BEFORE get_resource_data() to understand structure cheaply. Reads metadata and sample rows from the first downloadable resource.

Get dataset details. detail_level controls response size.

Download and parse a data file from data.gov.rs.

Parses JSON, CSV, XLSX, XLS, and XML automatically. Resource IDs come from get_dataset(detail_level="metadata").

Compare two datasets side by side. Helps choose the best dataset for analysis.

Shows differences in publisher, tags, resource count, formats, quality.

Discover newly added/updated datasets. Returns most recently modified first.

List the data files (resources) available for a specific dataset.

Use this before get_resource_data() to discover:

• Resource IDs (required by get_resource_data)

• Available formats (json, csv, xlsx, xls, xml)

• File descriptions and sizes

• Direct download URLs

Equivalent to get_dataset(detail_level="resources"), exposed as its own tool for callers that only need the file listing.

Quick schema summary of a resource's data without downloading the full file.

Returns column names, dtypes, row count, and sample values for the first few rows. Much faster than get_resource_data() for large XLSX/CSV files where you only need to know the schema.

Transform data: filter, group, aggregate, sort, or select columns.

Filter rows by criteria. Shorthand for transform_data(operation='filter').

Group data by one or more columns with optional aggregations.

Shorthand for transform_data(operation='group'). Returns one row per group with the requested aggregation(s) applied.

Aggregation functions: sum, mean, median, min, max, count, std, var.

Aggregate a single column using a function.

Shorthand for transform_data(operation='aggregate'). Returns the scalar result as {"value": ..., "column": ..., "function": ...}.

Functions: sum, mean, median, min, max, count, std, var.

Sort data by one or more columns.

Shorthand for transform_data(operation='sort').

Select specific columns from data, dropping all others.

Shorthand for transform_data(operation='select').

Create interactive charts from data. Supports 20+ chart types.

BASIC CHARTS (most common):

• "line": x_column + y_column → time series, trends

• "bar": x_column + y_column → comparisons, rankings

• "pie": values_column + names_column → proportions

• "scatter": x_column + y_column → correlations

• "histogram": x_column or y_column → frequency distributions

• "box": y_column (+ optional x_column) → statistical distributions

Apply visual theme to a chart figure from create_chart().

Themes: 'dark' (data-journalism), 'light' (clean), 'infographic' (large type). Add annotations: [{"text": "...", "x": val, "y": val}] for callouts. Add zones: [{"x_start": val, "x_end": val, "label": "..."}] for highlights.

Create a complete infographic HTML: headline + big number + chart + insights.

Self-contained HTML with responsive design. Opens in any browser. Saved to exports/ directory.

Returns: {filepath, metadata, insights, headline}

Build multi-panel dashboard HTML. Each panel: chart, HTML, or big number.

Add rich contextual tooltips to any Plotly figure.

Enriches hover with formatted values, deviation from mean, and rank. Without: 'Value: 7150000'. With: 'Value: 7.15M / Prosečno: 4.2M / Rank: #1'.

Returns: Enhanced figure dict

Add a callout annotation to a chart for storytelling.

Text box with optional arrow pointing to a data point.

Add a shaded vertical highlight zone to a chart.

Highlights a time period with a colored band. Ideal for: COVID years, crisis periods, policy changes.

Returns: Enhanced figure dict

Add multiple annotation callout boxes to highlight data points.

Each box has arrow pointing to data. Points: {x, y, text, color?, ax?, ay?}

Returns: Enhanced figure dict

Add a horizontal threshold/reference line with label.

Ideal for: EU average benchmark, target/goal line, critical threshold.

Returns: Enhanced figure dict

Create a styled, responsive HTML data table with conditional formatting.

Professional table with ranking indicators and value formatting. Highlights max or min value row.

Ideal for: district statistics, budget breakdowns, top-N listings.

Returns: {filepath, title, rows, total_rows, columns}

Understand data structure BEFORE creating charts or transforming.

Returns column names, types, unique counts, null counts, sample values. For numeric columns: min, max, mean, median.

ALWAYS use after get_resource_data() and before create_chart() to choose correct columns.

Extract surprising findings from data: extremes, trends, outliers, inequality.

Each insight has severity (critical/high/medium/low), headline, and narrative. Sorted by severity. Use AFTER data_profile() to identify time/entity columns.

Returns: {insights: [...], total_found, headline, severity_summary}

Generate a data story: headline, big number, narrative text.

Returns: {title, headline, big_number, big_label, insights, summary}

Compute derived metrics: YoY changes, per-capita, growth rates, index (base=100).

Returns: {yoy_changes, per_capita, growth_rates, index_values, derived_data}

Forecast future values using regression. 'At this rate, X by 2030.'

Returns: {forecast_data, growth_rate, projection_note, r_squared, historical_data, trend_line}

Compare against benchmarks (EU average, regional, custom).

Returns: {statistical_benchmarks, best_performer, worst_performer, comparisons, insights}

Extract insights by comparing two related datasets.

Finds correlations, divergences, and rank disagreements. Ideal for: 'population vs air quality' analyses.

Returns: {summary_a, summary_b, correlation, insights}

Choropleth map of Serbia by 25 administrative districts. Color-coded by metric.

District names in Natural Earth format (English transliteration). Cyrillic and city shorthand also supported (e.g., 'Niš', 'Novi Sad'). Use list_serbia_districts() to see all recognized names.

Returns: {filepath, districts_matched, total_districts, title}

List 25 administrative districts for create_serbia_map(). Returns recognized names.

Bubble map of Serbia — circle size = magnitude. Avoids large-district bias.

Returns: {filepath, districts_matched, title}

Multi-layer choropleth with toggle buttons between indicators.

Each layer: {data, name_column, value_column, label, colorscale}

Returns: {filepath, layer_count, title}

Save a chart from create_chart() to a file.

Save data from get_resource_data() or transform_data() to file.

Formats: 'csv' (universal), 'json' (API-friendly), 'xlsx' (requires openpyxl).

Export a chart to PDF. Requires kaleido (pip install kaleido).

Returns: {filepath, format, width, height} or {error} if kaleido missing

Generate iframe embed code for sharing a chart in websites/blogs.

Self-contained embed snippet pasteable into any website or CMS. Renders via Plotly.js CDN.

Returns: {iframe_code, width, height, note}

Export data to Datawrapper for professional cloud-hosted charts.

Creates a chart on Datawrapper (datawrapper.de) with your data, publishes it, and returns embed URLs and embed code. Requires the DATAWRAPPER_ACCESS_TOKEN environment variable.

Get a free API token at: https://app.datawrapper.de/account/api-tokens

Supported chart types:

• 'd3-bars-vertical' — vertical bar chart

• 'd3-bars-horizontal' — horizontal bar chart

• 'd3-lines' — line chart

• 'd3-area' — area chart

• 'd3-pies' — pie chart

• 'd3-pie-donut' — donut chart

• 'd3-scatter' — scatter plot

• 'd3-table' — data table

Check server health and API connectivity.

Get the current MCP server configuration settings.

Returns the resolved runtime configuration: API endpoint, rate limit, request timeout, and the cache/export directories. Useful for debugging connectivity or understanding where exported files are written.

Get statistics about the cached dataset catalog.

Summarizes the local catalog (used by intelligent_search/preview_dataset) without triggering a refresh: total datasets, distinct organizations and formats, downloadable count, and cache age.

Returns: {total_datasets, total_organizations, total_formats, downloadable_datasets, formats, organizations, cache_path, cache_age_hours, cache_exists}

Refresh the dataset catalog cache from data.gov.rs.

Re-fetches all datasets from the API and rebuilds the local cache used by intelligent_search() and preview_dataset(). The cache also auto-refreshes every 24h on first use; call this when you need fresh data immediately.

Returns: {total_datasets, cache_path, built_at, duration_seconds, timestamp}

Arrow-style chart showing directional changes. Green=positive, red=negative.

Ideal for: rankings change, budget surplus/deficit, growth/decline.

Returns: {filepath, title, rows}

Dumbbell chart: before/after comparison with connected dots.

Green=increase, red=decrease. Shows magnitude and direction.

Ideal for: population 2010 vs 2022, budget planned vs executed.

Returns: {filepath, title, rows}

Lollipop chart — dots on stems for clean ranking. Can highlight one entity.

Ideal for: district population ranking, budget by ministry, top-N lists.

Returns: {filepath, title, rows}

Slope chart: ranking changes between two periods with connecting lines.

Green=gained rank, red=lost rank.

Ideal for: census ranking 2002→2022, budget share shifts, district reorderings.

Returns: {filepath, title, rows}

Waffle chart (icon grid) for proportional data. 'X out of 100' visualization.

More intuitive than pie charts for showing proportions.

Ideal for: '1 in 4 Serbs live in Belgrade', budget share, sector breakdown.

Returns: {filepath, title, categories}

Population pyramid: age × sex distribution. Males left, females right.

Essential for census data from RZS. Classic demographic visualization.

Returns: {filepath, title, age_groups}

Sankey (alluvial) diagram showing flow between categories.

Ideal for: budget flow (revenue→ministry→spending), energy distribution, migration flows, supply chains.

Returns: {filepath, title, flows}

Radar/spider chart for multi-metric comparison.

Compare entities across multiple indicators on one radar plot.

Ideal for: comparing districts on population+budget+schools+hospitals+air quality.

Returns: {filepath, title, entities, metrics}

Create animated charts with smooth transitions and play/pause.

Create a scroll-driven HTML data story (scrollytelling).

Multi-section page with narrative text scrolling left and interactive charts updating right — the visualise.admin.ch pattern.

Interactive 3D scatter / bubble chart (WebGL, orbit-able).

Plots three numeric dimensions as points in 3-space, with optional color, bubble size, and marker shape encoding up to three more variables.

Ideal for: spatial data (lat/lon/altitude), district × year × population, exploring three census indicators at once.

Returns: {filepath, title, rows}

Interactive 3D line / trajectory chart (WebGL, orbit-able).

Connects points through 3-space — a trajectory. Split into one line per category via color_column.

Ideal for: a route through lat/lon/altitude, a metric evolving across region × time, multi-decade demographic trajectories.

Returns: {filepath, title, rows}

Interactive 3D surface (landscape) chart from gridded data (WebGL, orbit-able).

Long-format (x, y, z) rows are pivoted into a z-value grid and rendered as a continuous surface. Suited to elevation, density, or any scalar field sampled on a regular grid.

Ideal for: temperature/air-quality across city × month, terrain surfaces, optimization landscapes.

Returns: {filepath, title, rows}

Interactive 3D mesh from scattered points (WebGL, orbit-able).

Triangulates scattered (x, y, z) points into a connected surface or enclosing hull — unlike create_surface_3d which needs a regular grid. An optional intensity_column colors each vertex by a fourth metric.

Ideal for: irregular terrain/field point clouds, region bounding shapes, sparse 3D samples (e.g. pollution at uneven monitoring stations).

Returns: {filepath, title, rows}

Interactive 3D iso-surface from a volumetric scalar field (WebGL, orbit-able).

Renders the 3D boundary where value_column falls within [isomin, isomax] — a level set of a continuous fourth variable sampled across (x, y, z). The marching-cubes extraction runs client-side at render, so scattered samples are accepted without a regular grid or SciPy.

Ideal for: pollution/concentration thresholds across a 3D monitoring volume, isotherms, groundwater head surfaces, any "region where value ≥ threshold".

Returns: {filepath, title, rows}

Interactive 3D vector field / quiver plot (WebGL, orbit-able).

Renders a cone at each (x, y, z) anchor pointing along the vector (u, v, w) — a 3D arrow field of direction + magnitude. Cones are colored by vector magnitude and sized by sizeref. Distinct from the scalar 3D charts: a cone field encodes a vector (flow, gradient, force) at each sample point.

Ideal for: wind / air-flow fields, magnetic or electric fields, fluid-flow simulations, gradient directions across a 3D domain.

Returns: {filepath, title, rows}

Interactive 3D streamtube plot of a vector field's flow (WebGL, orbit-able).

Integrates the (u, v, w) vector field into streamlines rendered as tubes whose diameter encodes local flow magnitude. Distinct from create_cone_3d (one discrete arrow per sample): a streamtube shows the integrated trajectories — wind corridors, ocean currents, magnetic field lines — rather than the instantaneous direction at each point. The streamline integration runs client-side at render, so a sampled grid needs no SciPy or iterative solver.

Ideal for: wind / ocean circulation, ventilation or HVAC airflow, magnetic / electric field lines, any continuous flow domain where the path of the flow matters more than the per-point arrow.

Returns: {filepath, title, rows}

Interactive 3D volume render of a volumetric scalar field (WebGL, orbit-able).

Renders the full semi-transparent scalar field across (x, y, z) — a see-through cloud whose density + color encode value_column, with a configurable number of internal iso-surfaces. Distinct from create_isosurface_3d (which draws only the single boundary where value equals a threshold): a volume shows the interior distribution of the field, not just its level-set shell. The ray-marched rendering runs client-side, so scattered samples are accepted without a regular grid or SciPy.

Ideal for: 3D pollution / concentration clouds, temperature or humidity fields across a monitoring volume, groundwater head distributions, any scalar field where the interior structure — not just the boundary — matters.

Returns: {filepath, title, rows}