georgiacivicdata.rows#

georgiacivicdata.rows(name, *, year=None, detail=None, district=None, school=None, county=None, labels=True, columns=None, sort=None, n_max=None, cache=None, quiet=False, backend=None, **filters)#

Get rows of a dataset.

The core function: the rows of one dataset at one detail level, as a data frame typed from the dataset's schema, with place names beside their codes.

It returns every category and group the filters don't exclude. Nothing is pinned by default: no single demographic group, no single subject. A call with only a dataset name returns the whole dataset at its default detail level.

Filters. Give filters as keyword arguments; each value is one value or a list. Values within one filter are OR'd; different filters are AND'd. Accepted names:

any categorical column: subject="mathematics", demographic=["all", "black"];
geography codes: district_code, school_code, county_fips, tract_geoid, block_group_geoid;
school_id: schools as "DISTRICT-SCHOOL" codes (school_id=["761-0199", "660-0104"]), the form locate() returns (a school code alone is not unique across districts);
lookup-table attributes: district_type="state_charter", school_level="high", locale="rural", demographic_category="race";
metric bounds: graduation_rate_min=0.9, num_cohort_max=50 (inclusive, in stored units).

None inside a list selects rows where a nullable column is empty (assessment_type=[None]); a filter that is None itself is ignored. Booleans become true / false. The API validates every filter and its errors name what went wrong; describe() lists each dataset's filters and their values.

Labels. With labels=True (the default) the rows carry the API's joined name columns, each right after its code: district_name, district_census_id and district_type after district_code; school_name after school_code; county_name, tract_name and block_group_name after their codes; demographic_label and demographic_category after demographic. Codes are always kept: school names repeat across districts, names change over time, and joins run on codes. Categorical values (subject, grade_cluster) are readable snake_case codes already. Other lookup-table attributes (school addresses, locale, coordinates) are not joined; get them from dimension() and merge. labels=False asks for the dataset's own columns only, for large pulls. Either way, code columns that would be empty on every row (a district row's school_code, a state row's geography codes) are left out, so both settings give the same shape.

Missing values and totals. A missing metric usually means the value was suppressed to protect privacy (small counts), not zero; the schema's null_semantics says which (describe()). Because nothing is pinned, results hold the all totals beside the subgroups: never add a total to its subgroups. The API's advisories say so when they apply, as GCDAdvisory warnings (quiet=True or set_option("quiet", True) silences them; they stay in meta(df)["advisories"]). Rates must be pooled from their counts, never averaged: sum(num_graduates) / sum(num_cohort), not mean(graduation_rate). columns() shows each metric's numerator and denominator.

Large downloads and the disk cache. Up to 10,000 rows come back as one JSON page. A larger result is downloaded in full as CSV in one response; the metadata and advisories then come from the first JSON page and describe its first 10,000 rows. With cache=True (or set_option("cache", True)), responses are kept in the user cache folder with their ETag. Repeating a request asks the server whether the data changed: an unchanged answer reuses the saved copy without downloading, and a new data release downloads afresh. A response the server marks fresh (for five minutes) is reused without asking. Clear it with cache_clear().

Data license. The data is CC BY 4.0: credit Georgia Civic Data and the original source, as citation() writes.

Parameters:

name (str) -- The dataset's name, such as "graduation_rate_4_year_cohort" (see datasets() and search()).
year (int or list of int, optional) -- Years to keep. A run of consecutive years (range(2019, 2025)) is sent as a range; anything else ([2019, 2024]) as exact years. Default: all years.
detail (str, optional) -- The one level the rows describe, such as "schools", "districts", "states", "counties" or "tracts". Default: the dataset's default (the finest level, except Census datasets, which default to counties). To combine levels, call once per level and concatenate.
district (str or list of str, optional) -- Places by name, such as district="Fulton County", school="Roswell High School", county=["Fulton", "DeKalb"]. Matched exactly against current and former names (ignoring case, accents and a trailing "County"); an unknown or ambiguous name is an error that lists suggestions or candidates. A school name found in more than one district needs district too. For any one place, give its code or its name, not both.
school (str or list of str, optional) -- Places by name, such as district="Fulton County", school="Roswell High School", county=["Fulton", "DeKalb"]. Matched exactly against current and former names (ignoring case, accents and a trailing "County"); an unknown or ambiguous name is an error that lists suggestions or candidates. A school name found in more than one district needs district too. For any one place, give its code or its name, not both.
county (str or list of str, optional) -- Places by name, such as district="Fulton County", school="Roswell High School", county=["Fulton", "DeKalb"]. Matched exactly against current and former names (ignoring case, accents and a trailing "County"); an unknown or ambiguous name is an error that lists suggestions or candidates. A school name found in more than one district needs district too. For any one place, give its code or its name, not both.
labels (bool, default True) -- True adds place names beside codes; False returns codes only.
columns (str or list of str, optional) -- Return only these columns. Default: all.
sort (str or list of str, optional) -- Columns to sort by on the server; prefix - for descending ("-graduation_rate"). Missing values sort last. Mostly useful with n_max for a top N. Default: the dataset's own order (its grain).
n_max (int, optional) -- The most rows to return. Default None: all.
cache (bool, optional) -- True to use the disk cache. Default: the cache option (False).
quiet (bool, default False) -- True silences the advisories.
backend ({"pandas", "polars"}, optional) -- The kind of data frame to return. Default: the backend option ("pandas").
**filters -- Named filters (see "Filters" above).

Returns:

pandas.DataFrame or polars.DataFrame -- Rows at one detail level, typed from the schema: codes and names are strings (leading zeros kept), year and counts integers, rates and proportions floats (proportions on the 0-1 scale), booleans boolean. In pandas, integers are Int64, booleans boolean and text string (nullable dtypes); floats are float64. Columns come in grain order: year, each geography code followed by its names, demographic and its labels, other categorical columns, then metrics. columns() describes each column. meta() returns the response's metadata: dataset, title, detail, key metric, units, null_semantics, source, citation, license, advisories, data version, updated_at and the request URL.