# 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.
- `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.
- `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"
## Quick Start
```bash
pip install -i https://test.pypi.org/simple/ space2stats-client
```
```python
from space2stats 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](https://worldbank.github.io/DECAT_Space2Stats/).
## 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.
Raw data
{
"_id": null,
"home_page": null,
"name": "space2stats-client",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "gis, spatial, statistics, world bank, development",
"author": "World Bank",
"author_email": "worldbank@worldbank.org",
"download_url": "https://files.pythonhosted.org/packages/bd/f7/278307c4c70bd1ec4cb36060606b5a9abb2c8dfac130a9d4cc951c729f4c/space2stats_client-1.0.0.tar.gz",
"platform": null,
"description": "# Space2Stats Python Client\n\nA Python client for accessing the Space2Stats API, providing easy access to consistent, comparable, and authoritative sub-national variation data from the World Bank.\n\n\n## API Methods\n\n### `get_topics()`\nReturns a DataFrame containing available dataset themes/topics from the STAC catalog.\n\n### `get_fields()`\nReturns a list of all available fields that can be used with the API.\n\n### `get_properties(item_id: str)`\nReturns a DataFrame with descriptions of variables for a specific dataset.\n\n### `fetch_admin_boundaries(iso3: str, adm: str)`\nFetches administrative boundaries from GeoBoundaries API for a given country and admin level.\n\n### `get_summary(gdf, spatial_join_method, fields, geometry=None)`\nExtracts H3 level data for areas of interest.\n- `gdf`: GeoDataFrame containing areas of interest\n- `spatial_join_method`: \"touches\", \"centroid\", or \"within\"\n- `fields`: List of field names to retrieve\n- `geometry`: Optional \"polygon\" or \"point\" to include H3 geometries\n\n### `get_aggregate(gdf, spatial_join_method, fields, aggregation_type)`\nExtracts summary statistics from H3 data.\n- `gdf`: GeoDataFrame containing areas of interest\n- `spatial_join_method`: \"touches\", \"centroid\", or \"within\"\n- `fields`: List of field names to retrieve\n- `aggregation_type`: \"sum\", \"avg\", \"count\", \"max\", or \"min\"\n\n\n## Quick Start\n\n```bash\npip install -i https://test.pypi.org/simple/ space2stats-client\n```\n\n```python\nfrom space2stats import Space2StatsClient\nimport geopandas as gpd\n\n# Initialize the client\nclient = Space2StatsClient()\n\n# Get available topics/datasets\ntopics = client.get_topics()\nprint(topics)\n\n# Get fields for a specific dataset\nfields = client.get_fields(\"dataset_id\")\nprint(fields)\n\n# Get data for an area of interest\ngdf = gpd.read_file(\"path/to/your/area.geojson\")\nsummary = client.get_summary(\n gdf=gdf,\n spatial_join_method=\"centroid\",\n fields=[\"population\", \"gdp\"]\n)\n\n# Get aggregated statistics\naggregates = client.get_aggregate(\n gdf=gdf,\n spatial_join_method=\"centroid\",\n fields=[\"population\", \"gdp\"],\n aggregation_type=\"sum\"\n)\n```\n\n## Documentation\n\nFor full documentation, visit [Space2Stats Documentation](https://worldbank.github.io/DECAT_Space2Stats/).\n\n## License\n\nThis project is licensed under the World Bank Master Community License Agreement. See the LICENSE file for details.\n\n## Disclaimer\n\nThe 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. \n",
"bugtrack_url": null,
"license": "World Bank Master Community License Agreement",
"summary": "A Python client for accessing sub-national variation data through the Space2Stats API",
"version": "1.0.0",
"project_urls": {
"Documentation": "https://worldbank.github.io/DECAT_Space2Stats/",
"Homepage": "https://github.com/worldbank/DECAT_Space2Stats.git",
"Repository": "https://github.com/worldbank/DECAT_Space2Stats.git"
},
"split_keywords": [
"gis",
" spatial",
" statistics",
" world bank",
" development"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5efcc8645829694a3d559865117fadd4a8265d0dd243ab41814b2337f47ea8b6",
"md5": "93e6ab329d81a80ac10a3332c462b872",
"sha256": "4961cb86dd77804c3653b0c6c23eae181b77e018f437d65fcf34b15e409d71a8"
},
"downloads": -1,
"filename": "space2stats_client-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "93e6ab329d81a80ac10a3332c462b872",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 5060,
"upload_time": "2025-02-13T11:40:26",
"upload_time_iso_8601": "2025-02-13T11:40:26.210825Z",
"url": "https://files.pythonhosted.org/packages/5e/fc/c8645829694a3d559865117fadd4a8265d0dd243ab41814b2337f47ea8b6/space2stats_client-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "bdf7278307c4c70bd1ec4cb36060606b5a9abb2c8dfac130a9d4cc951c729f4c",
"md5": "0e230909492c1183c9729e0d60a8a1bd",
"sha256": "85cf35714f35332f7afa87e19d1fa0e8bd8b843bbaacf87f74ede31620174d68"
},
"downloads": -1,
"filename": "space2stats_client-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "0e230909492c1183c9729e0d60a8a1bd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 3956,
"upload_time": "2025-02-13T11:40:29",
"upload_time_iso_8601": "2025-02-13T11:40:29.437194Z",
"url": "https://files.pythonhosted.org/packages/bd/f7/278307c4c70bd1ec4cb36060606b5a9abb2c8dfac130a9d4cc951c729f4c/space2stats_client-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-13 11:40:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "worldbank",
"github_project": "DECAT_Space2Stats",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "space2stats-client"
}
JSON
