Handlers¶

A handler acquires a dataset published as files, stores the files, and loads them for a source. Construct the handler, then call load_data, load_into_dataframe, or the method named below. The shared machinery is documented in the handler base, not on these pages.

from gigaspatial import GHSLDataHandler, WPPopulationHandler
from gigaspatial.handlers import GHSLDataConfig, GHSLDataDownloader, GHSLDataReader

Every handler is importable from gigaspatial. Its config, downloader, and reader are in gigaspatial.handlers. A handler takes its config fields as keyword arguments, so most scripts only need the handler.

GHSL¶

Bases: BaseHandler

Handler for GHSL (Global Human Settlement Layer) dataset.

This class provides a unified interface for downloading and loading GHSL data. It manages the lifecycle of configuration, downloading, and reading components.

`load_data(source, crop_to_source=False, ensure_available=True, **kwargs)` ¶

Load data from a source, ensuring its availability first.

This is the primary high-level method for users to retrieve data from a handler.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame, Path, List[Union[str, Path]]]`	Specification of the data to load.	required
`crop_to_source`	`bool`	If True, crops the result to the source geometry.	`False`
`ensure_available`	`bool`	If True, downloads missing data before loading.	`True`
`**kwargs`		Resolve, download and read options.	`{}`

Returns:

Type	Description
`Any`	The loaded data object.

Raises:

Type	Description
`TypeError`	If a keyword is not an option of any component.
`RuntimeError`	If data availability cannot be ensured.

`download_and_load(source, crop_to_source=False, force_download=False, **kwargs)` ¶

Download (if missing) and load data in a single call.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame, Path, List[Union[str, Path]]]`	Specification of the data to acquire and load.	required
`crop_to_source`	`bool`	If True, crops the result to the source geometry.	`False`
`force_download`	`bool`	If True, re-downloads data even if present.	`False`
`**kwargs`		Resolve, download and read options.	`{}`

Returns:

Type	Description
`Any`	The loaded data object.

Raises:

Type	Description
`TypeError`	If a keyword is not an option of any component.

`ensure_data_available(source, force_download=False, **kwargs)` ¶

Guarantee that the required data for a source exists in the DataStore.

Resolves the source into data units and downloads those that are not stored yet (config.is_unit_available), or all of them if force_download is True. Path sources are only checked for existence.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame, Path, List[Union[str, Path]]]`	Specification of the required data.	required
`force_download`	`bool`	If True, downloads every unit regardless of local state.	`False`
`**kwargs`		Resolve and download options.	`{}`

Returns:

Type	Description
`bool`	True if all required data is available in the DataStore, False if
`bool`	some units (or explicit paths) are still missing after the
`bool`	download attempt.

Raises:

Type	Description
`TypeError`	If a keyword is neither a resolve nor a download option.
`Exception`	Errors raised while resolving the source into data units or paths propagate unchanged, as do programming errors (`TypeError`, `AttributeError`, `NameError`) raised while downloading. Other download errors are logged per unit, and the availability check that follows decides the return value.

`get_available_data_info(source, **kwargs)` ¶

Determine the availability status of data for a given source.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame]`	Specification of the data to check.	required
`**kwargs`		Resolve options.	`{}`

Returns:

Type	Description
`dict`	A dictionary with the number of available and missing data units,
`dict`	and the stored paths that exist and do not exist.

Raises:

Type	Description
`TypeError`	If a keyword is not a resolve option.

`load_into_dataframe(source, crop_to_source=False, ensure_available=True, **kwargs)` ¶

Load GHSL data into a pandas DataFrame.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame, Path, List[Union[str, Path]]]`	The data source specification	required
`ensure_available`	`bool`	If True, ensure data is downloaded before loading	`True`
`**kwargs`		Handler options go to `load_data`, the rest to `TifProcessor.to_dataframe`.	`{}`

Returns:

Type	Description
`DataFrame`	DataFrame containing the GHSL data

`load_into_geodataframe(source, crop_to_source=False, ensure_available=True, **kwargs)` ¶

Load GHSL data into a geopandas GeoDataFrame.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame, Path, List[Union[str, Path]]]`	The data source specification	required
`ensure_available`	`bool`	If True, ensure data is downloaded before loading	`True`
`**kwargs`		Handler options go to `load_data`, the rest to `TifProcessor.to_geodataframe`.	`{}`

Returns:

Type	Description
`GeoDataFrame`	GeoDataFrame containing the GHSL data

WorldPop¶

Bases: BaseHandler

Handler for WorldPop Populations datasets.

This class provides a unified interface for downloading and loading WP Population data. It manages the lifecycle of configuration, downloading, and reading components.

`load_data(source, crop_to_source=False, ensure_available=True, **kwargs)` ¶

Load data from a source, ensuring its availability first.

This is the primary high-level method for users to retrieve data from a handler.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame, Path, List[Union[str, Path]]]`	Specification of the data to load.	required
`crop_to_source`	`bool`	If True, crops the result to the source geometry.	`False`
`ensure_available`	`bool`	If True, downloads missing data before loading.	`True`
`**kwargs`		Resolve, download and read options.	`{}`

Returns:

Type	Description
`Any`	The loaded data object.

Raises:

Type	Description
`TypeError`	If a keyword is not an option of any component.
`RuntimeError`	If data availability cannot be ensured.

`download_and_load(source, crop_to_source=False, force_download=False, **kwargs)` ¶

Download (if missing) and load data in a single call.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame, Path, List[Union[str, Path]]]`	Specification of the data to acquire and load.	required
`crop_to_source`	`bool`	If True, crops the result to the source geometry.	`False`
`force_download`	`bool`	If True, re-downloads data even if present.	`False`
`**kwargs`		Resolve, download and read options.	`{}`

Returns:

Type	Description
`Any`	The loaded data object.

Raises:

Type	Description
`TypeError`	If a keyword is not an option of any component.

`ensure_data_available(source, force_download=False, **kwargs)` ¶

Guarantee that the required data for a source exists in the DataStore.

Resolves the source into data units and downloads those that are not stored yet (config.is_unit_available), or all of them if force_download is True. Path sources are only checked for existence.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame, Path, List[Union[str, Path]]]`	Specification of the required data.	required
`force_download`	`bool`	If True, downloads every unit regardless of local state.	`False`
`**kwargs`		Resolve and download options.	`{}`

Returns:

Type	Description
`bool`	True if all required data is available in the DataStore, False if
`bool`	some units (or explicit paths) are still missing after the
`bool`	download attempt.

Raises:

Type	Description
`TypeError`	If a keyword is neither a resolve nor a download option.
`Exception`	Errors raised while resolving the source into data units or paths propagate unchanged, as do programming errors (`TypeError`, `AttributeError`, `NameError`) raised while downloading. Other download errors are logged per unit, and the availability check that follows decides the return value.

`get_available_data_info(source, **kwargs)` ¶

Determine the availability status of data for a given source.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame]`	Specification of the data to check.	required
`**kwargs`		Resolve options.	`{}`

Returns:

Type	Description
`dict`	A dictionary with the number of available and missing data units,
`dict`	and the stored paths that exist and do not exist.

Raises:

Type	Description
`TypeError`	If a keyword is not a resolve option.

`load_into_dataframe(source, ensure_available=True, **kwargs)` ¶

Acquire WorldPop data and load it into a tabular DataFrame.

Parameters:

Name	Type	Description	Default
`source`	`str`	Geographic area (country ISO3).	required
`ensure_available`	`bool`	If True, executes download if data is missing locally.	`True`
`**kwargs`		Handler options go to `load_data`, the rest to `TifProcessor.to_dataframe`.	`{}`

Returns:

Type	Description
`DataFrame`	A pandas DataFrame containing demographic data.

`load_into_geodataframe(source, ensure_available=True, **kwargs)` ¶

Acquire WorldPop data and load it into a geospatial GeoDataFrame.

Parameters:

Name	Type	Description	Default
`source`	`str`	Geographic area (country ISO3).	required
`ensure_available`	`bool`	If True, executes download if data is missing locally.	`True`
`**kwargs`		Handler options go to `load_data`, the rest to `TifProcessor.to_geodataframe`.	`{}`

Returns:

Type	Description
`GeoDataFrame`	A GeoDataFrame containing demographic data with geometries.

Google Open Buildings¶

Bases: BaseHandler

Unified handler for the Google Open Buildings dataset.

Provides a top-level API for acquiring and accessing building footprints across multiple geometry formats (points and polygons).

`load_data(source, crop_to_source=False, ensure_available=True, **kwargs)` ¶

Load data from a source, ensuring its availability first.

This is the primary high-level method for users to retrieve data from a handler.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame, Path, List[Union[str, Path]]]`	Specification of the data to load.	required
`crop_to_source`	`bool`	If True, crops the result to the source geometry.	`False`
`ensure_available`	`bool`	If True, downloads missing data before loading.	`True`
`**kwargs`		Resolve, download and read options.	`{}`

Returns:

Type	Description
`Any`	The loaded data object.

Raises:

Type	Description
`TypeError`	If a keyword is not an option of any component.
`RuntimeError`	If data availability cannot be ensured.

`download_and_load(source, crop_to_source=False, force_download=False, **kwargs)` ¶

Download (if missing) and load data in a single call.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame, Path, List[Union[str, Path]]]`	Specification of the data to acquire and load.	required
`crop_to_source`	`bool`	If True, crops the result to the source geometry.	`False`
`force_download`	`bool`	If True, re-downloads data even if present.	`False`
`**kwargs`		Resolve, download and read options.	`{}`

Returns:

Type	Description
`Any`	The loaded data object.

Raises:

Type	Description
`TypeError`	If a keyword is not an option of any component.

`ensure_data_available(source, force_download=False, **kwargs)` ¶

Guarantee that the required data for a source exists in the DataStore.

Resolves the source into data units and downloads those that are not stored yet (config.is_unit_available), or all of them if force_download is True. Path sources are only checked for existence.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame, Path, List[Union[str, Path]]]`	Specification of the required data.	required
`force_download`	`bool`	If True, downloads every unit regardless of local state.	`False`
`**kwargs`		Resolve and download options.	`{}`

Returns:

Type	Description
`bool`	True if all required data is available in the DataStore, False if
`bool`	some units (or explicit paths) are still missing after the
`bool`	download attempt.

Raises:

Type	Description
`TypeError`	If a keyword is neither a resolve nor a download option.
`Exception`	Errors raised while resolving the source into data units or paths propagate unchanged, as do programming errors (`TypeError`, `AttributeError`, `NameError`) raised while downloading. Other download errors are logged per unit, and the availability check that follows decides the return value.

`get_available_data_info(source, **kwargs)` ¶

Determine the availability status of data for a given source.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame]`	Specification of the data to check.	required
`**kwargs`		Resolve options.	`{}`

Returns:

Type	Description
`dict`	A dictionary with the number of available and missing data units,
`dict`	and the stored paths that exist and do not exist.

Raises:

Type	Description
`TypeError`	If a keyword is not a resolve option.

`load_points(source, crop_to_source=False, ensure_available=True, **kwargs)` ¶

Load point data from Google Open Buildings dataset.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame, Path, List[Union[str, Path]]]`	The data source specification	required
`ensure_available`	`bool`	If True, ensure data is downloaded before loading	`True`
`**kwargs`		Additional parameters passed to load methods	`{}`

Returns:

Type	Description
`GeoDataFrame`	GeoDataFrame containing building point data

`load_polygons(source, crop_to_source=False, ensure_available=True, **kwargs)` ¶

Load polygon data from Google Open Buildings dataset.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame, Path, List[Union[str, Path]]]`	The data source specification	required
`ensure_available`	`bool`	If True, ensure data is downloaded before loading	`True`
`**kwargs`		Additional parameters passed to load methods	`{}`

Returns:

Type	Description
`GeoDataFrame`	GeoDataFrame containing building polygon data

Microsoft buildings¶

Bases: BaseHandler

Unified handler for the Microsoft Global Buildings dataset.

Provides a top-level API for acquiring and accessing Microsoft building footprints for any geographic region.

`load_data(source, crop_to_source=False, ensure_available=True, **kwargs)` ¶

Load data from a source, ensuring its availability first.

This is the primary high-level method for users to retrieve data from a handler.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame, Path, List[Union[str, Path]]]`	Specification of the data to load.	required
`crop_to_source`	`bool`	If True, crops the result to the source geometry.	`False`
`ensure_available`	`bool`	If True, downloads missing data before loading.	`True`
`**kwargs`		Resolve, download and read options.	`{}`

Returns:

Type	Description
`Any`	The loaded data object.

Raises:

Type	Description
`TypeError`	If a keyword is not an option of any component.
`RuntimeError`	If data availability cannot be ensured.

`download_and_load(source, crop_to_source=False, force_download=False, **kwargs)` ¶

Download (if missing) and load data in a single call.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame, Path, List[Union[str, Path]]]`	Specification of the data to acquire and load.	required
`crop_to_source`	`bool`	If True, crops the result to the source geometry.	`False`
`force_download`	`bool`	If True, re-downloads data even if present.	`False`
`**kwargs`		Resolve, download and read options.	`{}`

Returns:

Type	Description
`Any`	The loaded data object.

Raises:

Type	Description
`TypeError`	If a keyword is not an option of any component.

`ensure_data_available(source, force_download=False, **kwargs)` ¶

Guarantee that the required data for a source exists in the DataStore.

Resolves the source into data units and downloads those that are not stored yet (config.is_unit_available), or all of them if force_download is True. Path sources are only checked for existence.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame, Path, List[Union[str, Path]]]`	Specification of the required data.	required
`force_download`	`bool`	If True, downloads every unit regardless of local state.	`False`
`**kwargs`		Resolve and download options.	`{}`

Returns:

Type	Description
`bool`	True if all required data is available in the DataStore, False if
`bool`	some units (or explicit paths) are still missing after the
`bool`	download attempt.

Raises:

Type	Description
`TypeError`	If a keyword is neither a resolve nor a download option.
`Exception`	Errors raised while resolving the source into data units or paths propagate unchanged, as do programming errors (`TypeError`, `AttributeError`, `NameError`) raised while downloading. Other download errors are logged per unit, and the availability check that follows decides the return value.

`get_available_data_info(source, **kwargs)` ¶

Determine the availability status of data for a given source.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame]`	Specification of the data to check.	required
`**kwargs`		Resolve options.	`{}`

Returns:

Type	Description
`dict`	A dictionary with the number of available and missing data units,
`dict`	and the stored paths that exist and do not exist.

Raises:

Type	Description
`TypeError`	If a keyword is not a resolve option.

Google and Microsoft buildings¶

Bases: BaseHandler

Handler for Google-Microsoft Combined Buildings Dataset.

Provides end-to-end workflow for downloading, caching, and reading merged Google V3 Open Buildings and Microsoft Global Building Footprints.

Features: - Cloud-native GeoParquet streaming - Automatic partition discovery by geometry - Source filtering (Google/Microsoft) - Confidence score filtering - Local caching for repeated access

Example

config = GoogleMSBuildingsConfig() handler = GoogleMSBuildingsHandler(config) geometry = Polygon([...]) # Your area of interest buildings = handler.load_data(geometry)

`load_data(source, crop_to_source=False, ensure_available=True, **kwargs)` ¶

Load data from a source, ensuring its availability first.

This is the primary high-level method for users to retrieve data from a handler.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame, Path, List[Union[str, Path]]]`	Specification of the data to load.	required
`crop_to_source`	`bool`	If True, crops the result to the source geometry.	`False`
`ensure_available`	`bool`	If True, downloads missing data before loading.	`True`
`**kwargs`		Resolve, download and read options.	`{}`

Returns:

Type	Description
`Any`	The loaded data object.

Raises:

Type	Description
`TypeError`	If a keyword is not an option of any component.
`RuntimeError`	If data availability cannot be ensured.

`download_and_load(source, crop_to_source=False, force_download=False, **kwargs)` ¶

Download (if missing) and load data in a single call.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame, Path, List[Union[str, Path]]]`	Specification of the data to acquire and load.	required
`crop_to_source`	`bool`	If True, crops the result to the source geometry.	`False`
`force_download`	`bool`	If True, re-downloads data even if present.	`False`
`**kwargs`		Resolve, download and read options.	`{}`

Returns:

Type	Description
`Any`	The loaded data object.

Raises:

Type	Description
`TypeError`	If a keyword is not an option of any component.

`ensure_data_available(source, force_download=False, **kwargs)` ¶

Guarantee that the required data for a source exists in the DataStore.

Resolves the source into data units and downloads those that are not stored yet (config.is_unit_available), or all of them if force_download is True. Path sources are only checked for existence.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame, Path, List[Union[str, Path]]]`	Specification of the required data.	required
`force_download`	`bool`	If True, downloads every unit regardless of local state.	`False`
`**kwargs`		Resolve and download options.	`{}`

Returns:

Type	Description
`bool`	True if all required data is available in the DataStore, False if
`bool`	some units (or explicit paths) are still missing after the
`bool`	download attempt.

Raises:

Type	Description
`TypeError`	If a keyword is neither a resolve nor a download option.
`Exception`	Errors raised while resolving the source into data units or paths propagate unchanged, as do programming errors (`TypeError`, `AttributeError`, `NameError`) raised while downloading. Other download errors are logged per unit, and the availability check that follows decides the return value.

`get_available_data_info(source, **kwargs)` ¶

Determine the availability status of data for a given source.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame]`	Specification of the data to check.	required
`**kwargs`		Resolve options.	`{}`

Returns:

Type	Description
`dict`	A dictionary with the number of available and missing data units,
`dict`	and the stored paths that exist and do not exist.

Raises:

Type	Description
`TypeError`	If a keyword is not a resolve option.

`load_centroids(source, force=False, **kwargs)` ¶

Loads and concatenates the easy-access centroid caches for a given source. Automatically generates the caches if they do not exist.

Parameters:

Name	Type	Description	Default
`source`		specification of the data to load (e.g., iso3 code, geometry).	required
`force`	`bool`	If True, forces regeneration of the cache.	`False`
`**kwargs`		Resolve and download options.	`{}`

Returns:

Type	Description
`Dict[str, ndarray]`	Dictionary containing combined numpy arrays (e.g., {'coords': np.ndarray})

HDX¶

Bases: BaseHandler

Unified handler for HDX datasets.

Provides a streamlined API for interacting with the HDX platform, allowing for dataset-specific configuration and resource-level access.

`load_data(source, crop_to_source=False, ensure_available=True, **kwargs)` ¶

Load data from a source, ensuring its availability first.

This is the primary high-level method for users to retrieve data from a handler.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame, Path, List[Union[str, Path]]]`	Specification of the data to load.	required
`crop_to_source`	`bool`	If True, crops the result to the source geometry.	`False`
`ensure_available`	`bool`	If True, downloads missing data before loading.	`True`
`**kwargs`		Resolve, download and read options.	`{}`

Returns:

Type	Description
`Any`	The loaded data object.

Raises:

Type	Description
`TypeError`	If a keyword is not an option of any component.
`RuntimeError`	If data availability cannot be ensured.

`download_and_load(source, crop_to_source=False, force_download=False, **kwargs)` ¶

Download (if missing) and load data in a single call.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame, Path, List[Union[str, Path]]]`	Specification of the data to acquire and load.	required
`crop_to_source`	`bool`	If True, crops the result to the source geometry.	`False`
`force_download`	`bool`	If True, re-downloads data even if present.	`False`
`**kwargs`		Resolve, download and read options.	`{}`

Returns:

Type	Description
`Any`	The loaded data object.

Raises:

Type	Description
`TypeError`	If a keyword is not an option of any component.

`ensure_data_available(source, force_download=False, **kwargs)` ¶

Guarantee that the required data for a source exists in the DataStore.

Resolves the source into data units and downloads those that are not stored yet (config.is_unit_available), or all of them if force_download is True. Path sources are only checked for existence.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame, Path, List[Union[str, Path]]]`	Specification of the required data.	required
`force_download`	`bool`	If True, downloads every unit regardless of local state.	`False`
`**kwargs`		Resolve and download options.	`{}`

Returns:

Type	Description
`bool`	True if all required data is available in the DataStore, False if
`bool`	some units (or explicit paths) are still missing after the
`bool`	download attempt.

Raises:

Type	Description
`TypeError`	If a keyword is neither a resolve nor a download option.
`Exception`	Errors raised while resolving the source into data units or paths propagate unchanged, as do programming errors (`TypeError`, `AttributeError`, `NameError`) raised while downloading. Other download errors are logged per unit, and the availability check that follows decides the return value.

`get_available_data_info(source, **kwargs)` ¶

Determine the availability status of data for a given source.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame]`	Specification of the data to check.	required
`**kwargs`		Resolve options.	`{}`

Returns:

Type	Description
`dict`	A dictionary with the number of available and missing data units,
`dict`	and the stored paths that exist and do not exist.

Raises:

Type	Description
`TypeError`	If a keyword is not a resolve option.

Relative Wealth Index¶

Bases: HDXHandler

Unified handler for Relative Wealth Index data.

Coordinates acquisition, reading, and quadkey-based spatial processing of wealth index resources.

`load_data(source, crop_to_source=False, ensure_available=True, **kwargs)` ¶

Acquire and process RWI data, ensuring quadkey availability.

Parameters:

Name	Type	Description	Default
`source`		Geographic source or direct file paths.	required
`crop_to_source`	`bool`	If True, filters results to the source boundary.	`False`
`ensure_available`	`bool`	If True, executes download if data is missing locally.	`True`
`**kwargs`		Additional processing parameters.	`{}`

Returns:

Type	Description
	A pandas DataFrame of wealth index results with quadkeys.

`download_and_load(source, crop_to_source=False, force_download=False, **kwargs)` ¶

Download (if missing) and load data in a single call.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame, Path, List[Union[str, Path]]]`	Specification of the data to acquire and load.	required
`crop_to_source`	`bool`	If True, crops the result to the source geometry.	`False`
`force_download`	`bool`	If True, re-downloads data even if present.	`False`
`**kwargs`		Resolve, download and read options.	`{}`

Returns:

Type	Description
`Any`	The loaded data object.

Raises:

Type	Description
`TypeError`	If a keyword is not an option of any component.

`ensure_data_available(source, force_download=False, **kwargs)` ¶

Guarantee that the required data for a source exists in the DataStore.

Resolves the source into data units and downloads those that are not stored yet (config.is_unit_available), or all of them if force_download is True. Path sources are only checked for existence.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame, Path, List[Union[str, Path]]]`	Specification of the required data.	required
`force_download`	`bool`	If True, downloads every unit regardless of local state.	`False`
`**kwargs`		Resolve and download options.	`{}`

Returns:

Type	Description
`bool`	True if all required data is available in the DataStore, False if
`bool`	some units (or explicit paths) are still missing after the
`bool`	download attempt.

Raises:

Type	Description
`TypeError`	If a keyword is neither a resolve nor a download option.
`Exception`	Errors raised while resolving the source into data units or paths propagate unchanged, as do programming errors (`TypeError`, `AttributeError`, `NameError`) raised while downloading. Other download errors are logged per unit, and the availability check that follows decides the return value.

`get_available_data_info(source, **kwargs)` ¶

Determine the availability status of data for a given source.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame]`	Specification of the data to check.	required
`**kwargs`		Resolve options.	`{}`

Returns:

Type	Description
`dict`	A dictionary with the number of available and missing data units,
`dict`	and the stored paths that exist and do not exist.

Raises:

Type	Description
`TypeError`	If a keyword is not a resolve option.

`load_as_geodataframe(source, crop_to_source=False, ensure_available=True, **kwargs)` ¶

Acquire and load RWI data as a geospatial GeoDataFrame of tiles.

Parameters:

Name	Type	Description	Default
`source`		Geographic source or direct file paths.	required
`crop_to_source`	`bool`	If True, filters results to the source boundary.	`False`
`ensure_available`	`bool`	If True, executes download if data is missing locally.	`True`
`**kwargs`		Additional processing parameters.	`{}`

Returns:

Type	Description
	A GeoDataFrame containing wealth index data mapped to spatial tiles.

Ookla¶

Bases: BaseHandler

Unified handler for Ookla Speedtest data.

Coordinates configuration, downloading, and spatial filtering of Ookla performance tiles using Mercator tile indices.

`load_data(source=None, crop_to_source=True, process_geospatial=False, ensure_available=True, **kwargs)` ¶

Acquire and filter Ookla Speedtest data.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[Tuple[float, float], Point]], BaseGeometry, GeoDataFrame, Path, str, List[Union[str, Path]]]`	Geographic filter (country, geometry, points) or direct file paths. None loads the whole quarter.	`None`
`crop_to_source`	`bool`	If True, keeps only the tiles intersecting the source. Path sources and None are never cropped.	`True`
`process_geospatial`	`bool`	If True, returns a GeoDataFrame with tile geometries.	`False`
`ensure_available`	`bool`	If True, executes download if data is missing locally.	`True`
`**kwargs`		Handler options (e.g. `show_progress`).	`{}`

Returns:

Type	Description
`Union[DataFrame, GeoDataFrame]`	Tabular or geospatial data for the requested area.

`download_and_load(source, crop_to_source=False, force_download=False, **kwargs)` ¶

Download (if missing) and load data in a single call.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame, Path, List[Union[str, Path]]]`	Specification of the data to acquire and load.	required
`crop_to_source`	`bool`	If True, crops the result to the source geometry.	`False`
`force_download`	`bool`	If True, re-downloads data even if present.	`False`
`**kwargs`		Resolve, download and read options.	`{}`

Returns:

Type	Description
`Any`	The loaded data object.

Raises:

Type	Description
`TypeError`	If a keyword is not an option of any component.

`ensure_data_available(source, force_download=False, **kwargs)` ¶

Guarantee that the required data for a source exists in the DataStore.

Resolves the source into data units and downloads those that are not stored yet (config.is_unit_available), or all of them if force_download is True. Path sources are only checked for existence.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame, Path, List[Union[str, Path]]]`	Specification of the required data.	required
`force_download`	`bool`	If True, downloads every unit regardless of local state.	`False`
`**kwargs`		Resolve and download options.	`{}`

Returns:

Type	Description
`bool`	True if all required data is available in the DataStore, False if
`bool`	some units (or explicit paths) are still missing after the
`bool`	download attempt.

Raises:

Type	Description
`TypeError`	If a keyword is neither a resolve nor a download option.
`Exception`	Errors raised while resolving the source into data units or paths propagate unchanged, as do programming errors (`TypeError`, `AttributeError`, `NameError`) raised while downloading. Other download errors are logged per unit, and the availability check that follows decides the return value.

`get_available_data_info(source, **kwargs)` ¶

Determine the availability status of data for a given source.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame]`	Specification of the data to check.	required
`**kwargs`		Resolve options.	`{}`

Returns:

Type	Description
`dict`	A dictionary with the number of available and missing data units,
`dict`	and the stored paths that exist and do not exist.

Raises:

Type	Description
`TypeError`	If a keyword is not a resolve option.

OpenCellID¶

Bases: BaseHandler

Unified handler for OpenCellID data.

Coordinates automated link discovery, coordinated downloads, and standardized reading of cell tower datasets.

`load_data(source, crop_to_source=False, ensure_available=True, **kwargs)` ¶

Load data from a source, ensuring its availability first.

This is the primary high-level method for users to retrieve data from a handler.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame, Path, List[Union[str, Path]]]`	Specification of the data to load.	required
`crop_to_source`	`bool`	If True, crops the result to the source geometry.	`False`
`ensure_available`	`bool`	If True, downloads missing data before loading.	`True`
`**kwargs`		Resolve, download and read options.	`{}`

Returns:

Type	Description
`Any`	The loaded data object.

Raises:

Type	Description
`TypeError`	If a keyword is not an option of any component.
`RuntimeError`	If data availability cannot be ensured.

`download_and_load(source, crop_to_source=False, force_download=False, **kwargs)` ¶

Download (if missing) and load data in a single call.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame, Path, List[Union[str, Path]]]`	Specification of the data to acquire and load.	required
`crop_to_source`	`bool`	If True, crops the result to the source geometry.	`False`
`force_download`	`bool`	If True, re-downloads data even if present.	`False`
`**kwargs`		Resolve, download and read options.	`{}`

Returns:

Type	Description
`Any`	The loaded data object.

Raises:

Type	Description
`TypeError`	If a keyword is not an option of any component.

`ensure_data_available(source, force_download=False, **kwargs)` ¶

Guarantee that the required data for a source exists in the DataStore.

Resolves the source into data units and downloads those that are not stored yet (config.is_unit_available), or all of them if force_download is True. Path sources are only checked for existence.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame, Path, List[Union[str, Path]]]`	Specification of the required data.	required
`force_download`	`bool`	If True, downloads every unit regardless of local state.	`False`
`**kwargs`		Resolve and download options.	`{}`

Returns:

Type	Description
`bool`	True if all required data is available in the DataStore, False if
`bool`	some units (or explicit paths) are still missing after the
`bool`	download attempt.

Raises:

Type	Description
`TypeError`	If a keyword is neither a resolve nor a download option.
`Exception`	Errors raised while resolving the source into data units or paths propagate unchanged, as do programming errors (`TypeError`, `AttributeError`, `NameError`) raised while downloading. Other download errors are logged per unit, and the availability check that follows decides the return value.

`get_available_data_info(source, **kwargs)` ¶

Determine the availability status of data for a given source.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame]`	Specification of the data to check.	required
`**kwargs`		Resolve options.	`{}`

Returns:

Type	Description
`dict`	A dictionary with the number of available and missing data units,
`dict`	and the stored paths that exist and do not exist.

Raises:

Type	Description
`TypeError`	If a keyword is not a resolve option.

`load_as_geodataframe(source, crop_to_source=False, ensure_available=True, **kwargs)` ¶

Acquire OpenCellID data and load it as a geospatial GeoDataFrame.

Parameters:

Name	Type	Description	Default
`source`		Geographic filter (country ISO) or direct file paths.	required
`crop_to_source`	`bool`	If True, clips data to the source boundary.	`False`
`ensure_available`	`bool`	If True, executes download if data is missing locally.	`True`
`**kwargs`		Additional parameters passed to `load_data`.	`{}`

Returns:

Type	Description
`GeoDataFrame`	A GeoDataFrame containing cell tower locations.

NASA SRTM¶

Bases: BaseHandler

Main handler class for NASA SRTM elevation data.

`load_data(source, crop_to_source=False, ensure_available=True, **kwargs)` ¶

Load data from a source, ensuring its availability first.

This is the primary high-level method for users to retrieve data from a handler.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame, Path, List[Union[str, Path]]]`	Specification of the data to load.	required
`crop_to_source`	`bool`	If True, crops the result to the source geometry.	`False`
`ensure_available`	`bool`	If True, downloads missing data before loading.	`True`
`**kwargs`		Resolve, download and read options.	`{}`

Returns:

Type	Description
`Any`	The loaded data object.

Raises:

Type	Description
`TypeError`	If a keyword is not an option of any component.
`RuntimeError`	If data availability cannot be ensured.

`download_and_load(source, crop_to_source=False, force_download=False, **kwargs)` ¶

Download (if missing) and load data in a single call.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame, Path, List[Union[str, Path]]]`	Specification of the data to acquire and load.	required
`crop_to_source`	`bool`	If True, crops the result to the source geometry.	`False`
`force_download`	`bool`	If True, re-downloads data even if present.	`False`
`**kwargs`		Resolve, download and read options.	`{}`

Returns:

Type	Description
`Any`	The loaded data object.

Raises:

Type	Description
`TypeError`	If a keyword is not an option of any component.

`ensure_data_available(source, force_download=False, **kwargs)` ¶

Guarantee that the required data for a source exists in the DataStore.

Resolves the source into data units and downloads those that are not stored yet (config.is_unit_available), or all of them if force_download is True. Path sources are only checked for existence.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame, Path, List[Union[str, Path]]]`	Specification of the required data.	required
`force_download`	`bool`	If True, downloads every unit regardless of local state.	`False`
`**kwargs`		Resolve and download options.	`{}`

Returns:

Type	Description
`bool`	True if all required data is available in the DataStore, False if
`bool`	some units (or explicit paths) are still missing after the
`bool`	download attempt.

Raises:

Type	Description
`TypeError`	If a keyword is neither a resolve nor a download option.
`Exception`	Errors raised while resolving the source into data units or paths propagate unchanged, as do programming errors (`TypeError`, `AttributeError`, `NameError`) raised while downloading. Other download errors are logged per unit, and the availability check that follows decides the return value.

`get_available_data_info(source, **kwargs)` ¶

Determine the availability status of data for a given source.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame]`	Specification of the data to check.	required
`**kwargs`		Resolve options.	`{}`

Returns:

Type	Description
`dict`	A dictionary with the number of available and missing data units,
`dict`	and the stored paths that exist and do not exist.

Raises:

Type	Description
`TypeError`	If a keyword is not a resolve option.

GloFAS flood hazard¶

Bases: BaseHandler

Handler for GloFAS flood hazard maps.

A geometry or a country selects the intersecting tiles. One load fetches one layer and, for depth layers, one return period:

GlofasHandler().load_data(geometry)
GlofasHandler().load_data("KEN", layer="depth_reclass", return_period=50)
GlofasHandler().load_data(geometry, layer="permanent_water")

`load_data(source, crop_to_source=False, ensure_available=True, **kwargs)` ¶

Load data from a source, ensuring its availability first.

This is the primary high-level method for users to retrieve data from a handler.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame, Path, List[Union[str, Path]]]`	Specification of the data to load.	required
`crop_to_source`	`bool`	If True, crops the result to the source geometry.	`False`
`ensure_available`	`bool`	If True, downloads missing data before loading.	`True`
`**kwargs`		Resolve, download and read options.	`{}`

Returns:

Type	Description
`Any`	The loaded data object.

Raises:

Type	Description
`TypeError`	If a keyword is not an option of any component.
`RuntimeError`	If data availability cannot be ensured.

`download_and_load(source, crop_to_source=False, force_download=False, **kwargs)` ¶

Download (if missing) and load data in a single call.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame, Path, List[Union[str, Path]]]`	Specification of the data to acquire and load.	required
`crop_to_source`	`bool`	If True, crops the result to the source geometry.	`False`
`force_download`	`bool`	If True, re-downloads data even if present.	`False`
`**kwargs`		Resolve, download and read options.	`{}`

Returns:

Type	Description
`Any`	The loaded data object.

Raises:

Type	Description
`TypeError`	If a keyword is not an option of any component.

`ensure_data_available(source, force_download=False, **kwargs)` ¶

Guarantee that the required data for a source exists in the DataStore.

Resolves the source into data units and downloads those that are not stored yet (config.is_unit_available), or all of them if force_download is True. Path sources are only checked for existence.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame, Path, List[Union[str, Path]]]`	Specification of the required data.	required
`force_download`	`bool`	If True, downloads every unit regardless of local state.	`False`
`**kwargs`		Resolve and download options.	`{}`

Returns:

Type	Description
`bool`	True if all required data is available in the DataStore, False if
`bool`	some units (or explicit paths) are still missing after the
`bool`	download attempt.

Raises:

Type	Description
`TypeError`	If a keyword is neither a resolve nor a download option.
`Exception`	Errors raised while resolving the source into data units or paths propagate unchanged, as do programming errors (`TypeError`, `AttributeError`, `NameError`) raised while downloading. Other download errors are logged per unit, and the availability check that follows decides the return value.

`get_available_data_info(source, **kwargs)` ¶

Determine the availability status of data for a given source.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame]`	Specification of the data to check.	required
`**kwargs`		Resolve options.	`{}`

Returns:

Type	Description
`dict`	A dictionary with the number of available and missing data units,
`dict`	and the stored paths that exist and do not exist.

Raises:

Type	Description
`TypeError`	If a keyword is not a resolve option.

OpenStreetMap roads¶

OSMRoadsHandler returns a SpatialNetwork built from Geofabrik's extracts, the same network OSMRoadsFetcher returns for the same area. It needs pip install "giga-spatial[roads]"; the road networks guide explains which extracts a source uses and how they are stored.

Bases: BaseHandler

OpenStreetMap road networks from Geofabrik extracts.

Stores each extract once and returns a SpatialNetwork for a country, a geometry, a frame, or points, the same network OSMRoadsFetcher returns for the same area. Suited to whole countries and regions; for a city or the area around a few schools, the fetcher downloads less.

Options, passed as keywords to load_data and the other entries:

choosing extracts: regions, extracts, date, refresh, max_age_days, buffer, area (OSMRoadsResolveOptions);
the network: network_type, tags, simplify, retain_all, truncate_by_edge, node_index (OSMRoadsReadOptions).

Example

from gigaspatial import OSMRoadsHandler handler = OSMRoadsHandler() rwanda = handler.load_data("RWA") around_schools = handler.load_data([(-1.9441, 30.0619), (-1.9536, 30.0588)], buffer=2000)

Needs pip install 'giga-spatial[roads]'.

`load_data(source, crop_to_source=True, ensure_available=True, **kwargs)` ¶

The road network of a source, downloading its extracts first when they are not stored.

Parameters:

Name	Type	Description	Default
`source`	`Any`	Country name or code, shapely geometry, GeoDataFrame, DataFrame with latitude and longitude columns, list of `(lat, lon)` tuples or Points, or paths of stored `.osm.pbf` files or saved network folders.	required
`crop_to_source`	`bool`	Crop to the source's area, as `OSMRoadsFetcher` does. True by default. A country whose extracts are its own file or its regions is used whole.	`True`
`ensure_available`	`bool`	Download missing extracts first.	`True`
`**kwargs`	`Any`	Resolve, download, and read options.	`{}`

Returns:

Type	Description
`Optional[SpatialNetwork]`	A directed `SpatialNetwork` in EPSG:4326 with lengths in meters.

Raises:

Type	Description
`TypeError`	If a keyword is not an option.
`RuntimeError`	If an extract could not be downloaded.
`ValueError`	If no extract covers the source, or the area has no matching roads.

`download_and_load(source, crop_to_source=True, force_download=False, **kwargs)` ¶

Download the source's extracts when missing, or always with force_download, then load its road network.

Parameters:

Name	Type	Description	Default
`source`	`Any`	As for `load_data`.	required
`crop_to_source`	`bool`	Crop to the source's area. True by default.	`True`
`force_download`	`bool`	Download the extracts again even when stored.	`False`
`**kwargs`	`Any`	Resolve, download, and read options.	`{}`

`ensure_data_available(source, force_download=False, **kwargs)` ¶

Guarantee that the required data for a source exists in the DataStore.

Resolves the source into data units and downloads those that are not stored yet (config.is_unit_available), or all of them if force_download is True. Path sources are only checked for existence.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame, Path, List[Union[str, Path]]]`	Specification of the required data.	required
`force_download`	`bool`	If True, downloads every unit regardless of local state.	`False`
`**kwargs`		Resolve and download options.	`{}`

Returns:

Type	Description
`bool`	True if all required data is available in the DataStore, False if
`bool`	some units (or explicit paths) are still missing after the
`bool`	download attempt.

Raises:

Type	Description
`TypeError`	If a keyword is neither a resolve nor a download option.
`Exception`	Errors raised while resolving the source into data units or paths propagate unchanged, as do programming errors (`TypeError`, `AttributeError`, `NameError`) raised while downloading. Other download errors are logged per unit, and the availability check that follows decides the return value.

`get_available_data_info(source, **kwargs)` ¶

Determine the availability status of data for a given source.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame]`	Specification of the data to check.	required
`**kwargs`		Resolve options.	`{}`

Returns:

Type	Description
`dict`	A dictionary with the number of available and missing data units,
`dict`	and the stored paths that exist and do not exist.

Raises:

Type	Description
`TypeError`	If a keyword is not a resolve option.

Bases: ResolveOptions

Options that choose the extracts for a source.

Attributes:

Name	Type	Description
`regions`	`bool`	For a country source, use the country's sub-region extracts instead of its country extract.
`extracts`	`Optional[Tuple[str, ...]]`	Geofabrik extract IDs to use, overriding the choice.
`date`	`Optional[str]`	Use the extracts of this date (`YYYY-MM-DD`), stored or downloaded, instead of the newest stored ones. Geofabrik keeps daily files for about a week, then those of the 1^st of each month and of January 1^st.
`refresh`	`bool`	Use Geofabrik's latest extracts even when older ones are stored, and download Geofabrik's index again.
`max_age_days`	`Optional[int]`	Use Geofabrik's latest extracts when the newest stored one is older than this many days. Never, by default.
`buffer`	`float`	Meters around point and line sources.
`area`	`Literal['hull', 'bbox', 'buffers']`	How points become an area: `"hull"`, `"bbox"`, or `"buffers"`.

Bases: ReadOptions

Options for building and loading road networks.

Attributes:

Name	Type	Description
`network_type`	`str`	osmnx network type, such as `"drive_service"`, `"drive"`, `"walk"`, `"bike"`, `"all_public"`, or `"all"`.
`tags`	`Optional[Dict[str, Optional[Sequence[str]]]]`	Allowed values per OSM key, such as `{"highway": ["primary", "secondary"]}`, replacing `network_type`. A way must match every key; `None` allows any value of a key.
`simplify`	`bool`	Join edges between junctions, as osmnx does.
`retain_all`	`bool`	Keep every disconnected part, not only the largest.
`truncate_by_edge`	`bool`	Keep edges that leave the area at one end.
`node_index`	`Optional[str]`	pyosmium node location index, such as `"flex_mem"` or `"sparse_file_array"`. Chosen from the extract's size otherwise.

WRI Aqueduct¶

Bases: BaseHandler

Unified handler for WRI Aqueduct Global Flood Hazard data.

Orchestrates configuration, downloading, and reading of global flood inundation depth rasters.

Examples¶

Riverine — historical 1-in-100-year flood:

handler = AqueductFloodHandler( ... flood_type="inunriver", ... climate_scenario="historical", ... year="1980", ... return_period="rp00100", ... model="000000000WATCH", ... ) tif = handler.load_data(schools_gdf)

Coastal — RCP 8.5 2050 with subsidence:

handler = AqueductFloodHandler( ... flood_type="inuncoast", ... climate_scenario="rcp8p5", ... year="2050", ... return_period="rp0100", ... subsidence="wtsub", ... projection="0_perc_50", ... ) tif = handler.load_data("RWA")

`load_data(source, crop_to_source=True, ensure_available=True, **kwargs)` ¶

`download_and_load(source, crop_to_source=False, force_download=False, **kwargs)` ¶

Download (if missing) and load data in a single call.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame, Path, List[Union[str, Path]]]`	Specification of the data to acquire and load.	required
`crop_to_source`	`bool`	If True, crops the result to the source geometry.	`False`
`force_download`	`bool`	If True, re-downloads data even if present.	`False`
`**kwargs`		Resolve, download and read options.	`{}`

Returns:

Type	Description
`Any`	The loaded data object.

Raises:

Type	Description
`TypeError`	If a keyword is not an option of any component.

`ensure_data_available(source, force_download=False, **kwargs)` ¶

Guarantee that the required data for a source exists in the DataStore.

Resolves the source into data units and downloads those that are not stored yet (config.is_unit_available), or all of them if force_download is True. Path sources are only checked for existence.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame, Path, List[Union[str, Path]]]`	Specification of the required data.	required
`force_download`	`bool`	If True, downloads every unit regardless of local state.	`False`
`**kwargs`		Resolve and download options.	`{}`

Returns:

Type	Description
`bool`	True if all required data is available in the DataStore, False if
`bool`	some units (or explicit paths) are still missing after the
`bool`	download attempt.

Raises:

Type	Description
`TypeError`	If a keyword is neither a resolve nor a download option.
`Exception`	Errors raised while resolving the source into data units or paths propagate unchanged, as do programming errors (`TypeError`, `AttributeError`, `NameError`) raised while downloading. Other download errors are logged per unit, and the availability check that follows decides the return value.

`get_available_data_info(source, **kwargs)` ¶

Determine the availability status of data for a given source.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, List[Union[tuple, Point]], BaseGeometry, GeoDataFrame]`	Specification of the data to check.	required
`**kwargs`		Resolve options.	`{}`

Returns:

Type	Description
`dict`	A dictionary with the number of available and missing data units,
`dict`	and the stored paths that exist and do not exist.

Raises:

Type	Description
`TypeError`	If a keyword is not a resolve option.

Handlers¶

GHSL¶

load_data(source, crop_to_source=False, ensure_available=True, **kwargs) ¶

download_and_load(source, crop_to_source=False, force_download=False, **kwargs) ¶

ensure_data_available(source, force_download=False, **kwargs) ¶

get_available_data_info(source, **kwargs) ¶

load_into_dataframe(source, crop_to_source=False, ensure_available=True, **kwargs) ¶

load_into_geodataframe(source, crop_to_source=False, ensure_available=True, **kwargs) ¶

WorldPop¶

load_data(source, crop_to_source=False, ensure_available=True, **kwargs) ¶

download_and_load(source, crop_to_source=False, force_download=False, **kwargs) ¶

ensure_data_available(source, force_download=False, **kwargs) ¶

get_available_data_info(source, **kwargs) ¶

load_into_dataframe(source, ensure_available=True, **kwargs) ¶

load_into_geodataframe(source, ensure_available=True, **kwargs) ¶

Google Open Buildings¶

load_data(source, crop_to_source=False, ensure_available=True, **kwargs) ¶

download_and_load(source, crop_to_source=False, force_download=False, **kwargs) ¶

ensure_data_available(source, force_download=False, **kwargs) ¶

get_available_data_info(source, **kwargs) ¶

load_points(source, crop_to_source=False, ensure_available=True, **kwargs) ¶

load_polygons(source, crop_to_source=False, ensure_available=True, **kwargs) ¶

Microsoft buildings¶

load_data(source, crop_to_source=False, ensure_available=True, **kwargs) ¶

download_and_load(source, crop_to_source=False, force_download=False, **kwargs) ¶

ensure_data_available(source, force_download=False, **kwargs) ¶

get_available_data_info(source, **kwargs) ¶

Google and Microsoft buildings¶

load_data(source, crop_to_source=False, ensure_available=True, **kwargs) ¶

download_and_load(source, crop_to_source=False, force_download=False, **kwargs) ¶

ensure_data_available(source, force_download=False, **kwargs) ¶

get_available_data_info(source, **kwargs) ¶

load_centroids(source, force=False, **kwargs) ¶

HDX¶

load_data(source, crop_to_source=False, ensure_available=True, **kwargs) ¶

download_and_load(source, crop_to_source=False, force_download=False, **kwargs) ¶

ensure_data_available(source, force_download=False, **kwargs) ¶

get_available_data_info(source, **kwargs) ¶

Relative Wealth Index¶

load_data(source, crop_to_source=False, ensure_available=True, **kwargs) ¶

download_and_load(source, crop_to_source=False, force_download=False, **kwargs) ¶

ensure_data_available(source, force_download=False, **kwargs) ¶

get_available_data_info(source, **kwargs) ¶

load_as_geodataframe(source, crop_to_source=False, ensure_available=True, **kwargs) ¶

Ookla¶

load_data(source=None, crop_to_source=True, process_geospatial=False, ensure_available=True, **kwargs) ¶

download_and_load(source, crop_to_source=False, force_download=False, **kwargs) ¶

ensure_data_available(source, force_download=False, **kwargs) ¶

get_available_data_info(source, **kwargs) ¶

OpenCellID¶

load_data(source, crop_to_source=False, ensure_available=True, **kwargs) ¶

download_and_load(source, crop_to_source=False, force_download=False, **kwargs) ¶

ensure_data_available(source, force_download=False, **kwargs) ¶

get_available_data_info(source, **kwargs) ¶

load_as_geodataframe(source, crop_to_source=False, ensure_available=True, **kwargs) ¶

NASA SRTM¶

load_data(source, crop_to_source=False, ensure_available=True, **kwargs) ¶

download_and_load(source, crop_to_source=False, force_download=False, **kwargs) ¶

ensure_data_available(source, force_download=False, **kwargs) ¶

get_available_data_info(source, **kwargs) ¶

GloFAS flood hazard¶

load_data(source, crop_to_source=False, ensure_available=True, **kwargs) ¶

download_and_load(source, crop_to_source=False, force_download=False, **kwargs) ¶

ensure_data_available(source, force_download=False, **kwargs) ¶

get_available_data_info(source, **kwargs) ¶

OpenStreetMap roads¶

load_data(source, crop_to_source=True, ensure_available=True, **kwargs) ¶

download_and_load(source, crop_to_source=True, force_download=False, **kwargs) ¶

ensure_data_available(source, force_download=False, **kwargs) ¶

get_available_data_info(source, **kwargs) ¶

WRI Aqueduct¶

Examples¶

load_data(source, crop_to_source=True, ensure_available=True, **kwargs) ¶

download_and_load(source, crop_to_source=False, force_download=False, **kwargs) ¶

ensure_data_available(source, force_download=False, **kwargs) ¶

get_available_data_info(source, **kwargs) ¶

load_into_dataframe(source, crop_to_source=True, ensure_available=True, min_value=0, **kwargs) ¶

load_into_geodataframe(source, crop_to_source=True, ensure_available=True, min_value=0, **kwargs) ¶

`load_data(source, crop_to_source=False, ensure_available=True, **kwargs)` ¶

`download_and_load(source, crop_to_source=False, force_download=False, **kwargs)` ¶

`ensure_data_available(source, force_download=False, **kwargs)` ¶

`get_available_data_info(source, **kwargs)` ¶

`load_into_dataframe(source, crop_to_source=False, ensure_available=True, **kwargs)` ¶

`load_into_geodataframe(source, crop_to_source=False, ensure_available=True, **kwargs)` ¶

`load_data(source, crop_to_source=False, ensure_available=True, **kwargs)` ¶

`download_and_load(source, crop_to_source=False, force_download=False, **kwargs)` ¶

`ensure_data_available(source, force_download=False, **kwargs)` ¶

`get_available_data_info(source, **kwargs)` ¶

`load_into_dataframe(source, ensure_available=True, **kwargs)` ¶

`load_into_geodataframe(source, ensure_available=True, **kwargs)` ¶

`load_data(source, crop_to_source=False, ensure_available=True, **kwargs)` ¶

`download_and_load(source, crop_to_source=False, force_download=False, **kwargs)` ¶

`ensure_data_available(source, force_download=False, **kwargs)` ¶

`get_available_data_info(source, **kwargs)` ¶

`load_points(source, crop_to_source=False, ensure_available=True, **kwargs)` ¶

`load_polygons(source, crop_to_source=False, ensure_available=True, **kwargs)` ¶

`load_data(source, crop_to_source=False, ensure_available=True, **kwargs)` ¶

`download_and_load(source, crop_to_source=False, force_download=False, **kwargs)` ¶

`ensure_data_available(source, force_download=False, **kwargs)` ¶

`get_available_data_info(source, **kwargs)` ¶

`load_data(source, crop_to_source=False, ensure_available=True, **kwargs)` ¶

`download_and_load(source, crop_to_source=False, force_download=False, **kwargs)` ¶

`ensure_data_available(source, force_download=False, **kwargs)` ¶

`get_available_data_info(source, **kwargs)` ¶

`load_centroids(source, force=False, **kwargs)` ¶

`load_data(source, crop_to_source=False, ensure_available=True, **kwargs)` ¶

`download_and_load(source, crop_to_source=False, force_download=False, **kwargs)` ¶

`ensure_data_available(source, force_download=False, **kwargs)` ¶

`get_available_data_info(source, **kwargs)` ¶

`load_data(source, crop_to_source=False, ensure_available=True, **kwargs)` ¶

`download_and_load(source, crop_to_source=False, force_download=False, **kwargs)` ¶

`ensure_data_available(source, force_download=False, **kwargs)` ¶

`get_available_data_info(source, **kwargs)` ¶

`load_as_geodataframe(source, crop_to_source=False, ensure_available=True, **kwargs)` ¶

`load_data(source=None, crop_to_source=True, process_geospatial=False, ensure_available=True, **kwargs)` ¶

`download_and_load(source, crop_to_source=False, force_download=False, **kwargs)` ¶

`ensure_data_available(source, force_download=False, **kwargs)` ¶

`get_available_data_info(source, **kwargs)` ¶

`load_data(source, crop_to_source=False, ensure_available=True, **kwargs)` ¶

`download_and_load(source, crop_to_source=False, force_download=False, **kwargs)` ¶

`ensure_data_available(source, force_download=False, **kwargs)` ¶

`get_available_data_info(source, **kwargs)` ¶

`load_as_geodataframe(source, crop_to_source=False, ensure_available=True, **kwargs)` ¶

`load_data(source, crop_to_source=False, ensure_available=True, **kwargs)` ¶

`download_and_load(source, crop_to_source=False, force_download=False, **kwargs)` ¶

`ensure_data_available(source, force_download=False, **kwargs)` ¶

`get_available_data_info(source, **kwargs)` ¶

`load_data(source, crop_to_source=False, ensure_available=True, **kwargs)` ¶

`download_and_load(source, crop_to_source=False, force_download=False, **kwargs)` ¶

`ensure_data_available(source, force_download=False, **kwargs)` ¶

`get_available_data_info(source, **kwargs)` ¶

`load_data(source, crop_to_source=True, ensure_available=True, **kwargs)` ¶

`download_and_load(source, crop_to_source=True, force_download=False, **kwargs)` ¶

`ensure_data_available(source, force_download=False, **kwargs)` ¶

`get_available_data_info(source, **kwargs)` ¶

`load_data(source, crop_to_source=True, ensure_available=True, **kwargs)` ¶

`download_and_load(source, crop_to_source=False, force_download=False, **kwargs)` ¶

`ensure_data_available(source, force_download=False, **kwargs)` ¶

`get_available_data_info(source, **kwargs)` ¶

`load_into_dataframe(source, crop_to_source=True, ensure_available=True, min_value=0, **kwargs)` ¶

`load_into_geodataframe(source, crop_to_source=True, ensure_available=True, min_value=0, **kwargs)` ¶