Search open-data catalogs for datasets (Socrata Discovery API).

Args: query: Full-text search, e.g. "crime reports" or "building permits". domain: Restrict to one portal, e.g. "data.seattle.gov". category: Portal category, e.g. "Public Safety". limit: Max results (default 20, cap 100). offset: Pagination offset into the result set.

Returns: {results: [{id, name, domain, description, updated_at, category, permalink}], count, total, offset}. Use each result's domain + id with the other tools.

Dataset metadata: columns with types, row count, update cadence, license.

Args: domain: Portal hostname, e.g. "data.seattle.gov". dataset_id: Socrata 4x4 id, e.g. "tazs-3rd5".

Returns: {name, description, columns: [{field_name, name, type, description}], row_count, license, attribution, created_at, data_updated_at, update_frequency, tags, source_url}. Use columns' field_name values in query/profile calls.

Query a dataset with structured SoQL parameters OR one raw SoQL string.

Structured mode (recommended): pass any of select/where/group/order/ limit/offset plus optional geo filters. Raw mode: pass soql only (e.g. "SELECT offense, count(*) GROUP BY offense LIMIT 50").

Args: domain: Portal hostname, e.g. "data.seattle.gov". dataset_id: Socrata 4x4 id, e.g. "tazs-3rd5". select: Columns/expressions, e.g. ["offense", "count(*) as n"]. where: SoQL filter, e.g. "offense_date > '2026-06-01T00:00:00'". group: GROUP BY columns (pair with aggregate select expressions). order: e.g. "offense_date DESC". Defaults to ":id" for stable paging. limit: Max rows returned (default 100, hard cap applies). offset: Row offset for pagination. soql: Raw SoQL query — mutually exclusive with all structured params. within_circle: {field, lat, lon, radius_m} geo filter on a point column. within_box: {field, nw_lat, nw_lon, se_lat, se_lon} geo filter.

Returns: {rows, row_count, truncated, query: {params, effective_limit, clamped}}. truncated: true means more rows matched than were returned — narrow the query or use export_csv for bulk extraction.

Profile every column: null rate, distinct count, min/max, top values.

Computed portal-side via aggregate SoQL — the dataset is never downloaded. Dates and numbers get min/max (numbers also avg); low-cardinality text columns get their top 10 values with counts.

Args: domain: Portal hostname, e.g. "data.seattle.gov". dataset_id: Socrata 4x4 id, e.g. "tazs-3rd5".

Returns: {row_count, columns: [{field_name, type, null_rate, non_null_count, distinct_count, min?, max?, avg?, top_values?, error?}], notes}.

Fetch the first n rows of a dataset (n capped at 100).

Args: domain: Portal hostname, e.g. "data.seattle.gov". dataset_id: Socrata 4x4 id, e.g. "tazs-3rd5". n: Number of rows (default 10, max 100).

Returns: {rows, row_count, note}. Rows are in :id order — a peek at real values, not a random sample.

Export query results to a Tableau-ready CSV via streamed, paged download.

Accepts the same query parameters as query (structured or raw soql) and writes matching rows to out_path. Designed to chain into vizforge's csv_to_dashboard. Point/location values are serialized as JSON strings.

Args: domain: Portal hostname, e.g. "data.seattle.gov". dataset_id: Socrata 4x4 id, e.g. "tazs-3rd5". out_path: Destination .csv path (parent directories are created). select/where/group/order/limit/soql/within_circle/within_box: as in query. max_rows: Safety cap for this export (default 1,000,000).

Returns: {path, rows_written, truncated, columns, notes}.