readers#

Low-level data-access functions for admin units and entities. Imported by internal modules (io/, geo/). Also re-exported from api.py.

Functions#

get_admin([admin_id, level, recipe, geom, columns, ...])

Get admin units of any administrative level

get_admin_ids(admin_level[, admin_id, admin_recipe])

Get list of administrative unit IDs

get_entities(recipe[, admin_id, geom, layer, partition_id])

Generic function to load a processed Parquet table for entities

get_dataset(recipe[, admin_id, partition_id, geom])

Load a processed dataset by recipe.

Module Contents#

openplaces.io.readers.get_admin(admin_id=None, level=None, recipe=None, geom=False, columns=None, all_columns=False, silent=True)#

Get admin units of any administrative level

Parameters:

  • admin_id (str, list, or openplaces.core.schema.AdminId) – Identifier(s) of admin units to return. Can include higher-level Admin IDs to select many lower levels

  • level (int) – Admin level for which to return units. If none, use level of admin_id (deepest if a list is passed).

  • recipe (str) – Use this recipe to import geometries and additional attributes.

  • geom (bool or 'simplified') – If False or None, return DataFrame without geometries. If True, return GeoDataFrame with geometries.

  • columns (list of str or None) – If a list of strings, will be used to select columns.

  • all_columns (bool) – If True, returns not only the most important columns

  • silent (True) – Silence warnings

  • geom – If False, return a DataFrame without geometries. If True, return a GeoDataFrame with full geometries. If 'simplified', return a GeoDataFrame with simplified geometries from the _geo_simplified companion file written by AdminHarmonizer.

openplaces.io.readers.get_admin_ids(admin_level, admin_id=None, admin_recipe=None)#

Get list of administrative unit IDs

openplaces.io.readers.get_entities(recipe, admin_id=None, geom=False, layer=None, partition_id=None)#

Generic function to load a processed Parquet table for entities

Entities are administrative units (admin), parcels, buildings, transactions, etc., as defined by the recipe.

Parameters:

  • recipe (str or dict) – Recipe that defines the entity. Can be a loaded recipe (dict) or a string of the recipe_id (which includes admin_id)

  • admin_id (str or AdminId) – Administrative unit for which to load the data. If None, choose admin_id of recipe.

  • geom (bool) – If True, include geometries and return a GeoDataFrame.

  • layer (str, optional) – Entity type (e.g. ‘property’) or full entity string (e.g. ‘property-massgis-2025’) of a secondary layer defined in additional_layers. If given, load that layer instead of the primary entity.

  • partition_id (str, optional) – Partition value to read a specific per-partition file, e.g. ‘032012’ for a tile-partitioned recipe. Pass None (default) to read the final merged output.

openplaces.io.readers.get_dataset(recipe, admin_id=None, partition_id=None, geom=False)#

Load a processed dataset by recipe.

Handles both raster and tabular dataset recipes. For raster datasets (Cloud Optimized GeoTIFFs written by fetch_rasters_by_admin), returns the path to the .tif file so the caller controls resource management (e.g. with rasterio or xarray). For tabular datasets, returns a DataFrame or GeoDataFrame exactly as get_entities does.

Parameters:

  • recipe (str or dict) – Recipe that defines the dataset. Can be a loaded recipe (dict) or a string recipe ID.

  • admin_id (str or AdminId, optional) – Administrative unit for which to load the data. If None, uses the admin_id from the recipe.

  • partition_id (str, optional) – Partition value to locate a specific partition file, e.g. ‘2020’ for a year-partitioned recipe. Pass None (default) for recipes without partitioning.

  • geom (bool) – If True, include geometries and return a GeoDataFrame. Ignored for raster datasets.

Returns:

  • Path – Path to the .tif file, for raster datasets.

  • pandas.DataFrame or geopandas.GeoDataFrame – Loaded tabular data, for non-raster datasets.

Raises:

ValueError – If the recipe does not have a ‘dataset’ key. Use get_entities for entity recipes.