georgiacivicdata.search

georgiacivicdata.search(query, main_topic=None, level=None, year=None, n=20, *, quiet=False, backend=None)

Search the catalog.

Ranked dataset search from plain words, in English or Spanish ("jobless rate", "kids missing school", "desempleo"). Use it when you know what you are looking for but not what the dataset is called.

Search is hybrid: keyword matching plus matching by meaning. The query text is sent to the Georgia Civic Data API, which embeds it with Voyage AI for the meaning half and never logs it. This is the one function whose results can't be reproduced by filtering datasets() locally, and the ranking can change between releases of the platform.

Parameters:

• query (str) -- Plain words.

• main_topic (optional) -- The same filters as datasets(): a subject area, a detail level and a year. Default: no filter.

• level (optional) -- The same filters as datasets(): a subject area, a detail level and a year. Default: no filter.

• year (optional) -- The same filters as datasets(): a subject area, a detail level and a year. Default: no filter.

• n (int, default 20) -- The number of matches to return, 1 to 100.

• quiet (bool, default False) -- True silences the notes on the search (see Returns).

• backend ({"pandas", "polars"}, optional) -- The kind of data frame to return. Default: the backend option.

Returns:

pandas.DataFrame or polars.DataFrame -- One row per match, best first, with columns:

• rank: integer, 1 is the best match.

• name, title, summary, main_topic: the dataset.

• detail_levels: list column of the levels it publishes.

• year_min, year_max: integers, the years covered.

• score: float, the match score.

• matched_on: list column of what matched (aliases, columns, summary, ...).

• matched_columns: list column of the dataset's columns that matched.

meta() on the result gives confidence ("high", "medium" or "low"), retrieval (a dict: mode and reranked) and total_matches. On low confidence the function advises that nothing in the catalog may fit; it also names any lookup tables that matched.

See also

datasets

the full catalog.

describe, columns

Examples

>>> import georgiacivicdata as gcd
>>> gcd.search("high school graduation")
>>> gcd.search("desempleo", n=5)
>>> gcd.search("chronic absence", level="districts")