Boundaries¶
AdminBoundaries loads administrative boundaries for a country. It is not a handler and not a fetcher. Handlers use it when a country source needs a geometry.
Bases: AdminBoundaryTable
Handler for administrative boundary data from multiple external sources.
Extends AdminBoundaryTable with factory methods that resolve and ingest boundaries from GADM, GeoRepo (UNICEF), geoBoundaries (HDX), Natural Earth, and internal data stores.
Examples:
>>> boundaries = AdminBoundaries.create("BRA", admin_level=1)
>>> gdf = boundaries.to_geodataframe()
boundaries property ¶
Backwards-compatible alias for entities.
Previously AdminBoundaries stored boundaries in a boundaries list field. This property maintains compatibility with any code that accesses .boundaries directly.
Returns:
| Type | Description |
|---|---|
List[AdminBoundary] | List of |
_create_empty() classmethod ¶
Return an empty AdminBoundaries instance.
_gdf_to_table(gdf, admin_level) classmethod ¶
Convert a GeoDataFrame (already column-mapped) into an AdminBoundaries instance.
Sets admin_level on every row and delegates validation to AdminBoundaryTable.from_dataframe.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
gdf | GeoDataFrame | GeoDataFrame with columns matching AdminBoundary field names. | required |
admin_level | int | Integer admin level to stamp on every entity. | required |
Returns:
| Type | Description |
|---|---|
'AdminBoundaries' | AdminBoundaries instance. |
_map_fields(gdf, source, current_level) classmethod ¶
Rename raw source columns to AdminBoundary field names.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
gdf | GeoDataFrame | Raw GeoDataFrame from the data source. | required |
source | str | Key in | required |
current_level | int | Admin level integer used for template substitution. | required |
Returns:
| Type | Description |
|---|---|
GeoDataFrame | GeoDataFrame with columns renamed to match AdminBoundary fields. |
_resolve_iso3(country_code) staticmethod ¶
Resolve any country identifier to ISO 3166-1 alpha-3.
_try_georepo(iso3_code, admin_level) classmethod ¶
Test GeoRepo connectivity without raising.
Returns:
| Type | Description |
|---|---|
bool | True if GeoRepo is reachable, False otherwise. |
create(country_code=None, admin_level=0, data_store=None, path=None, **kwargs) classmethod ¶
Unified factory method to resolve administrative boundaries.
Automatically selects the best available source in the following order: 1. Internal DataStore (if provided). 2. UNICEF GeoRepo API. 3. GADM 4.1. 4. geoBoundaries (HDX).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
country_code | Optional[str] | ISO country code or name. | None |
admin_level | int | Administrative level (0=country, 1=state, etc.). | 0 |
data_store | Optional[DataStore] | Optional DataStore for internal lookups. | None |
path | Optional[Union[str, Path]] | Optional specific file path in the DataStore. | None |
**kwargs | Forwarded to specific source loaders. | {} |
Returns:
| Type | Description |
|---|---|
'AdminBoundaries' | An AdminBoundaries instance. |
Raises:
| Type | Description |
|---|---|
ValueError | If essential parameters are missing or invalid. |
RuntimeError | If all data sources fail to resolve. |
from_data_store(path, data_store=None, admin_level=0, **kwargs) classmethod ¶
Load boundaries from an internal data store.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path | Union[str, Path] | Path to the dataset file within the store. | required |
data_store | DataStore | DataStore instance providing file access. | None |
admin_level | int | Administrative level (0-4). | 0 |
**kwargs | Additional arguments for | {} |
Returns:
| Type | Description |
|---|---|
'AdminBoundaries' | An AdminBoundaries instance. |
from_gadm(country_code, admin_level=0) classmethod ¶
Load boundaries from the GADM 4.1 dataset.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
country_code | str | ISO 3166-1 alpha-3 country code (e.g., "BRA"). | required |
admin_level | int | Administrative level (0-4). | 0 |
Returns:
| Type | Description |
|---|---|
'AdminBoundaries' | An AdminBoundaries instance populated from GADM. |
from_geoboundaries(country_code, admin_level=0) classmethod ¶
Load boundaries from the geoBoundaries dataset via HDX.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
country_code | str | ISO 3166-1 alpha-3 country code. | required |
admin_level | int | Administrative level (0-4). | 0 |
Returns:
| Type | Description |
|---|---|
'AdminBoundaries' | An AdminBoundaries instance populated from geoBoundaries. |
Raises:
| Type | Description |
|---|---|
ValueError | If no matching dataset or resource is found on HDX. |
from_georepo(country_code, admin_level=0) classmethod ¶
Load boundaries from the UNICEF GeoRepo API.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
country_code | str | ISO 3166-1 alpha-3 country code. | required |
admin_level | int | Administrative level (0-4). | 0 |
Returns:
| Type | Description |
|---|---|
'AdminBoundaries' | An AdminBoundaries instance populated from GeoRepo. |
from_global_country_boundaries(scale='medium') classmethod ¶
Load global country boundaries (admin level 0) from Natural Earth.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
scale | str | Resolution ('large' -> 10m, 'medium' -> 50m, 'small' -> 110m). | 'medium' |
Returns:
| Type | Description |
|---|---|
'AdminBoundaries' | An AdminBoundaries instance with global country polygons. |
Raises:
| Type | Description |
|---|---|
ValueError | If an invalid scale is provided. |