Release v1.4.1 – Fetch Admin Boundaries from Selected Source

Feature Update

Built-in Administrative Boundary Downloads

Space2StatsClient.fetch_admin_boundaries() now retrieves administrative boundaries directly from the World Bank’s ArcGIS service (ADM0–ADM2). Using the Source parameter, users can still fetch administrative boundaries from Geoboundaries instead if desired.

from space2stats_client import Space2StatsClient

client = Space2StatsClient()

# World Bank boundaries by default
adm1 = client.fetch_admin_boundaries("KEN", "ADM1")

# Swap to GeoBoundaries when you need the open data variant
adm1_gb = client.fetch_admin_boundaries("KEN", "ADM1", source="GB")

Release v1.4.0 – AOI Selector UI & ADM2 Summary Client

Release v1.4.0 – AOI Selector UI & ADM2 Summary Client

Feature Update

AOI Selector Widget

The Python client now includes an interactive AOI (Area of Interest) selection widget, allowing you to draw or choose geographic regions directly in Jupyter notebooks.

from space2stats_client import Space2StatsClient, AoiSelectorWidget

# Initialize the client
client = Space2StatsClient()

# Create and display the AOI selector widget
aoi_widget = AoiSelectorWidget(client)
aoi_widget.display()

# Retrieve the selected AOI geometry
selected_aoi = aoi_widget.get_selected_aoi()

ADM2 Summary Client Methods

New methods to fetch sub-national (ADM2) summary statistics from the DDH (Decentralized Data Hub) and return them as pandas DataFrames.

from space2stats_client import Space2StatsClient

# Initialize the client
client = Space2StatsClient()

# List available ADM2 summary datasets
dataset_info = client.get_adm2_dataset_info()
print(dataset_info)

# Fetch ADM2 summaries for a given dataset and country code
urban_data = client.get_adm2_summaries("urbanization", "AND")
print(urban_data.head())

Additional Improvements

• Updated client documentation with examples for both the AOI selector widget and the new ADM2 methods.
• Added tests covering the AOI widget integration and ADM2 summary methods.
• New UI widget structure to separate jupyter specific dependencies from core package functionality

Release v1.3.0 - Field Selector UI

Feature Update

Space2Stats now provides interactive widgets that make it easy to explore and select data fields in Jupyter notebooks.

CrossSectionFieldSelector

This widget helps users interactively select fields from the Space2Stats API for cross-sectional data. Fields are organized by their source STAC items for easier navigation.

from space2stats_client import Space2StatsClient, CrossSectionFieldSelector

# Initialize the client
client = Space2StatsClient()

# Create the field selector widget
selector = CrossSectionFieldSelector(client)

# Display the interactive widget in your notebook
selector.display()

# Later, retrieve the selected fields
selected_fields = selector.get_selected_fields()

# Use the selected fields in an API call
gdf = gpd.read_file("path/to/your/area.geojson")
summary = client.get_summary(
    gdf=gdf,
    spatial_join_method="centroid",
    fields=selected_fields
)

---

TimeSeriesFieldSelector

This widget allows users to interactively select fields for time series data and specify a valid time period based on the available data range.

from space2stats_client import Space2StatsClient, TimeSeriesFieldSelector

# Initialize the client
client = Space2StatsClient()

# Create the time series field selector widget
ts_selector = TimeSeriesFieldSelector(client)

# Display the interactive widget in your notebook
ts_selector.display()

# Later, retrieve the selected fields and time period
selections = ts_selector.get_selections()

# Use the selections in a time series API call
gdf = gpd.read_file("path/to/your/area.geojson")
timeseries_data = client.get_timeseries(
    gdf=gdf,
    spatial_join_method="centroid",
    fields=selections['fields'],
    start_date=selections['time_period']['start_date'].strftime('%Y-%m-%d'),
    end_date=selections['time_period']['end_date'].strftime('%Y-%m-%d')
)

---

Additional Improvements

• Improved error handling
• More descriptive error messages for too-large response and requests

Release v1.2.0 - New Timeseries Endpoints

Feature Update

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

Release 1.1.2 - Space2StatsClient

Feature Update

Adding a SSL bypass option. #119

Usage example

from space2stats_client import Space2StatsClient

# Create a client with SSL verification disabled
client = Space2StatsClient(verify_ssl=False)

# Now all API calls made with this client will bypass SSL verification
fields = client.get_fields()

Release v1.1.1 - Space2StatsClient

Bug Fixes

• Wrong url and import used in the quick start tutorial

Contributors

• @Gabe-Levin

Release v1.1.0 - Space2StatsClient

Release 1.1.0 - Space2StatsClient

Release Date: February 14, 2025

This release introduces new functionality to the Space2StatsClient, enhancing its capabilities with the addition of hex ID-based endpoints. These updates are designed to improve data retrieval and aggregation processes using H3 hexagon IDs.

New Features

• get_summary_by_hexids Method:

  • Added support for retrieving statistics for specific H3 hexagon IDs.
  • Example:

    summary_df = client.get_summary_by_hexids(
        hex_ids=["862a1070fffffff", "862a10767ffffff"],
        fields=["sum_pop_2020", "sum_pop_f_10_2020"],
        geometry="polygon"
    )

• get_aggregate_by_hexids Method:

  • Introduced functionality to aggregate statistics for specific H3 hexagon IDs.
  • Supports aggregation types: "sum", "avg", "count", "max", "min".
  • Example:

    aggregate_df = client.get_aggregate_by_hexids(
        hex_ids=["862a1070fffffff", "862a10767ffffff"],
        fields=["sum_pop_2020", "sum_pop_f_10_2020"],
        aggregation_type="sum"
    )

Improvements

• Documentation updates providing detailed instructions for the development workflow.
• Improved Readme Formatting

Contributors

• @Gabe-Levin

For more details, refer to the updated documentation

Release 1.0.0 - Space2StatsClient

Release 1.0.0 - Space2StatsClient

Release Date: February 14, 2025

This is the first release of the Space2Stats Client, a wrapper for the Space2Stats API. It offers essential features for data retrieval and aggregation, simplifying interactions with the S2S API.

Key Features

• get_topics:

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

• get_fields:

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

• get_properties:

  • Fetch descriptions of variables for a specific dataset.

• fetch_admin_boundaries :

  • Retrieve administrative boundaries from the GeoBoundaries API for a given country and admin level.

• get_summary:

  • Extract H3 level data for areas of interest.
  • Parameters include a GeoDataFrame, spatial join method, fields, and optional geometry.

• get_aggregate:

  • Extract summary statistics from H3 data.
  • Supports various aggregation types such as "sum", "avg", "count", "max", and "min".

Initial Setup

• Documentation to guide users through installation and usage.
• Example scripts to demonstrate the capabilities of the client.

Release v0.1.0rc0

Test Release

This release is being created to test the new github actions publication process for the space2stats client

Expected Behavior

This release should trigger the actions outlines in client-release.yml. It should run the tests within the space2stats_client sub-directory, and then publish the package to the pypi project site: https://pypi.org/project/space2stats-client/

Ideally the published package will inherit the version specified in the release tag