User Guide

Searching datasets

Use the search bar on the top page to search. Besides keywords, you can also type questions or natural sentences like “Where are the evacuation shelters?” — semantically related datasets are found in addition to keyword matches.

Semantic search

Datasets whose meaning is close to your query appear in the results even when no keyword matches, marked with a “Semantic match” badge. Turning off the “Include related results” toggle on the search results page limits results to keyword matches only.

Note: semantic search may be disabled depending on the site’s configuration (embedding model setup). In that case search works by keyword only.

Which resource matched

When a dataset holds several files, the results say which file matched — in a dataset of many files, what you are looking for is usually in one of them. Each matched resource carries a label saying why it matched.

Label	Meaning
Semantic match	The file’s meaning is close to the query. The number beside it is that closeness (0–1, higher is closer)
Matched the AI description	The query appears in that file’s AI-written description
Content match	The query appears in the file’s contents (the body of a CSV or text file)

When many files match, the list folds and shows the count.

Filtering

• Organization — Filter by the organization that published the data
• Category — Filter by data classification
• Tags — Filter by keyword tags
• Format — Filter by the formats of the dataset’s resources
• License — Filter by license

Sorting

Search results can be sorted by relevance, last updated, date created (newest/oldest), or URL identifier.

Browsing datasets

The dataset page displays the following information:

• Metadata — Title, description, author, license, etc.
• Resource list — Files and URLs included in the dataset, sometimes grouped under section headings (a heading also matches in search)
• Categories & tags — Classification information

Clicking a tag opens the list of datasets that carry it (/tag/<tag name>), as do the tags shown on each dataset in search results. An organization or category name likewise opens its list.

Resource preview

The resource page provides format-specific previews:

Format	Preview
CSV / TSV	Table view + text view
JSON	Table view + JSON view (where its records read as a table; otherwise JSON view alone)
XML / TXT / HTML	Text view
Markdown	Formatted (headings, tables, links) + source + extracted text; its text is searched under its headings
GeoJSON	Map view + attribute table + JSON view
PDF	PDF viewer + extracted text
Excel / Word / PowerPoint (the formats before 2007 included)	Office Online Viewer + extracted text
Ichitaro (JTD / JTT)	Original (drawn in the browser, a sheet at a time) + extracted text
PNG / JPEG / GIF / WebP / SVG / BMP / TIFF	Image viewer
ZIP	File list

A resource that gets a table view can also be opened straight from a BI tool such as Excel or Tableau (Opening the table in a BI tool).

AI-written descriptions

Note

This appears only where the site has the feature enabled. On a site without it, nothing described in this section appears on a resource page — nor does the “Matched the AI description” label in search results.

An AI-written description on a resource page is a short piece of prose an AI wrote from the file’s contents, so you can judge what is in it without opening it.

Below the description, a line says how much of the file it was written from. A table is read as its column layout and first rows (“Read the column layout and the first 100 of 1,200 rows”), while a PDF that fit is simply “Read the whole file” and an image “Read the whole image” (a very long PDF stops partway). Text files are read from their opening, Office documents and Markdown from the start of their extracted text, and ZIP archives from their file names, each with a line saying how much was read. Anything written from a part of a file always says so, so the extent is never left to guesswork.

Caution

An AI-written description is not a guarantee of accuracy or currency. Always check the original file for the authoritative content.

The description also names the version it was written from. If the file has been replaced and the description has not caught up, the page says so: “This file is now at v3; the description has not been rewritten.”

Some files get no description and a stated reason instead (over the size limit, a format the AI cannot read, and so on).

Downloading data

Click the “Download” button on the resource page to download a file. External URL resources also work through the same button (redirects to the original URL).

Opening the table in a BI tool

A tabular resource has an OData button. Copy the URL it shows, paste it into the OData connector in Tableau, Power BI, Excel and the like, and the table opens as it is — nothing to download and load.

• No credentials are needed (only public data is served). In Tableau, choose “No Authentication”
• In Excel: Data → Get Data → From Other Sources → From OData Feed
• Paste the connection URL shown first (the one ending in /Rows). The service URL below it also connects, but adds a step to pick the table — and a resource only ever has the one
• A large table is served in pages, and the BI tool follows them on its own
• What is served is the interpreted table: lines that could not be read — ones whose fields do not match the header, trailing notes — are not in it
• A RowId column may be added to tell rows apart. The button says what this particular table got, and you can drop that column in the BI tool if you do not want it
• Designating a primary key later changes the columns served (RowId appears or disappears). A BI tool already connected may keep showing the old ones through a refresh — rebuild the query there

Some tables cannot be served this way — headings with brackets or punctuation, for instance. The button is then dimmed, and pressing it says why.

Changing your password

If you sign in with a password, you can change it yourself from the profile page — no administrator involved.

A new password has to be:

• at least 15 characters, and
• hard to guess — a zxcvbn strength score of at least 3 (on a 0–4 scale).

Length alone is not enough. Common word sequences and keyboard patterns are rejected however long they are, and so is anything built out of your own email address, username, or display name. The strength meter updates as you type, so use it to gauge where you stand.

If you sign in through an external identity provider (OIDC), your password lives there and this section does not appear.

API access

KUKAN provides a REST API for programmatic data access. See the API documentation.

The rows of a tabular resource are also readable as an OData feed (/odata/v1/resources/{id}/Rows). To use one from a BI tool, see Opening the table in a BI tool.

# List datasets
curl https://your-kukan-site/api/v1/packages

# Search datasets
curl https://your-kukan-site/api/v1/packages?q=population