space2stats-client

Space2Stats Python Client

A Python client for accessing the Space2Stats API, providing easy access to consistent, comparable, and authoritative sub-national variation data from the World Bank.

API Methods

get_topics()

Returns a DataFrame containing available dataset themes/topics from the STAC catalog.

get_fields()

Returns a list of all available fields that can be used with the API.

get_properties(item_id: str)

Returns a DataFrame with descriptions of variables for a specific dataset.

fetch_admin_boundaries(iso3: str, adm: str)

Fetches administrative boundaries from GeoBoundaries API for a given country and admin level.

get_summary(gdf, spatial_join_method, fields, geometry=None)

Extracts H3 level data for areas of interest.

• Parameters:
  • gdf: GeoDataFrame containing areas of interest
  • spatial_join_method: "touches", "centroid", or "within"
  • fields: List of field names to retrieve
  • geometry: Optional "polygon" or "point" to include H3 geometries

get_aggregate(gdf, spatial_join_method, fields, aggregation_type)

Extracts summary statistics from H3 data.

• Parameters:
  • gdf: GeoDataFrame containing areas of interest
  • spatial_join_method: "touches", "centroid", or "within"
  • fields: List of field names to retrieve
  • aggregation_type: "sum", "avg", "count", "max", or "min"

get_summary_by_hexids(hex_ids, fields, geometry)

Retrieves statistics for specific H3 hexagon IDs.

• Parameters:
  • hex_ids: List of H3 hexagon IDs to query
  • fields: List of field names to retrieve
  • geometry: Optional; specifies if H3 geometries should be included ("polygon" or "point")

get_aggregate_by_hexids(hex_ids, fields, aggregation_type)

Aggregates statistics for specific H3 hexagon IDs.

• Parameters:
  • hex_ids: List of H3 hexagon IDs to aggregate
  • fields: List of field names to aggregate
  • aggregation_type: Type of aggregation ("sum", "avg", "count", "max", "min")

get_timeseries_fields()

Returns a list of available fields from the timeseries table.

get_timeseries(gdf, spatial_join_method, start_date=None, end_date=None, fields=None)

Gets timeseries data for areas of interest.

• Parameters:
  • gdf: GeoDataFrame containing areas of interest
  • spatial_join_method: "touches", "centroid", or "within"
  • start_date: Optional start date (format: 'YYYY-MM-DD')
  • end_date: Optional end date (format: 'YYYY-MM-DD')
  • fields: Optional list of field names to retrieve

get_timeseries_by_hexids(hex_ids, start_date=None, end_date=None, fields=None)

Gets timeseries data for specific H3 hexagon IDs.

• Parameters:
  • hex_ids: List of H3 hexagon IDs to query
  • start_date: Optional start date (format: 'YYYY-MM-DD')
  • end_date: Optional end date (format: 'YYYY-MM-DD')
  • fields: Optional list of field names to retrieve

Quick Start

pip install space2stats-client

from space2stats_client import Space2StatsClient
import geopandas as gpd

# Initialize the client
client = Space2StatsClient()

# Get available topics/datasets
topics = client.get_topics()
print(topics)

# Get fields for a specific dataset
fields = client.get_fields("dataset_id")
print(fields)

# Get data for an area of interest
gdf = gpd.read_file("path/to/your/area.geojson")
summary = client.get_summary(
    gdf=gdf,
    spatial_join_method="centroid",
    fields=["population", "gdp"]
)

# Get aggregated statistics
aggregates = client.get_aggregate(
    gdf=gdf,
    spatial_join_method="centroid",
    fields=["population", "gdp"],
    aggregation_type="sum"
)

Documentation

For full documentation, visit Space2Stats Documentation.

License

This project is licensed under the World Bank Master Community License Agreement. See the LICENSE file for details.

Disclaimer

The World Bank makes no warranties regarding the accuracy, reliability, or completeness of the results and content. The World Bank disclaims any liability arising from the use of this software.