administrative_area

Administrative boundaries retrieval and management module.

This module provides functionality to access and work with administrative area boundaries at various levels (countries, provinces, districts, etc.) using the GADM (Global Administrative Areas) database. It enables the retrieval of geographic boundaries for specific administrative areas within countries, which is a fundamental component for spatial analysis in public infrastructure planning.

Examples

Retrieve administrative boundaries for a country and its subdivisions:

>>> from pisa.administrative_area import AdministrativeArea
>>>
>>> # Get country-level boundaries
>>> country = AdministrativeArea("Timor-Leste", admin_level=0)
>>> country_boundary = country.get_admin_area_boundaries("Timor-Leste")
>>>
>>> # Get province-level boundaries
>>> provinces = AdministrativeArea("Timor-Leste", admin_level=1)
>>> province_names = provinces.get_admin_area_names()
>>> print(f"Provinces in Timor-Leste: {', '.join(province_names)}")
>>>
>>> # Get boundary for a specific province
>>> baucau_boundary = provinces.get_admin_area_boundaries("Baucau")

Attributes

logger

Classes

AdministrativeArea

Get the boundaries of administrative areas for a specified country.

Module Contents

administrative_area.logger

class administrative_area.AdministrativeArea(country_name: str, admin_level: int)

Get the boundaries of administrative areas for a specified country.

This class provides functionality to retrieve administrative area boundaries from the GADM (Global Administrative Areas) database for a specified country.

The administrative area level is specified by an integer, where 0 is the country level, 1 is the next broadest level (e.g., states or provinces), and so on.

Parameters:

country_name (str) – The name of the country for which to retrieve administrative areas
admin_level (int) – The administrative area level to retrieve (0 for country, 1 for first-level divisions, etc.)

See also

Facilities: Class for retrieving facilities within administrative areas
Population: Class for retrieving population data within administrative areas

Examples

>>> # Create an administrative area object for Timor-Leste at province level
>>> timor_leste = AdministrativeArea("Timor-Leste", admin_level=1)
>>>
>>> # Get a list of all administrative areas at this level
>>> print(timor_leste.get_admin_area_names())
>>>
>>> # Get the boundaries for a specific administrative area
>>> baucau_boundaries = timor_leste.get_admin_area_boundaries("Baucau")
>>>
>>> # Get the ISO3 country code for the country
>>> timor_leste_country_code = timor_leste.get_iso3_country_code()

country

admin_level

all_admin_areas_gdf = None

get_admin_area_names() → list[str]

Retrieve the names of all administrative areas for the specified level.

Returns:: List of administrative area names at the specified level. For admin_level=0, returns just the country name.
Return type:: list of str

get_admin_area_boundaries(admin_area_name: str) → shapely.Polygon | shapely.MultiPolygon

Return the boundary geometry for the specified administrative area.

Parameters:: admin_area_name (str) – Name of the administrative area to retrieve boundaries for. For admin_level=0, this parameter is ignored and the country boundary is returned.
Returns:: Geometry representing the administrative area boundaries
Return type:: shapely.geometry.Polygon or shapely.geometry.MultiPolygon
Raises:: ValueError – If admin_area_name is not found in the available administrative areas

get_iso3_country_code() → str

Retrieve the ISO 3166-1 alpha-3 country code for the country.

Returns:: The ISO 3166-1 alpha-3 country code in lowercase (e.g., tls for Timor-Leste)
Return type:: str