Metadata-Version: 2.4
Name: worldcountrygroups
Version: 0.3.0
Summary: Query international country groupings (EU, BRICS, G20, NATO, etc.)
License: MIT
License-File: LICENSE
Keywords: countries,groups,iso,geopolitics,international
Author: Tomas Gonzalez
Author-email: tomasgonz@gmail.com
Requires-Python: >=3.10,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries
Provides-Extra: api
Requires-Dist: fastapi (>=0.100) ; extra == "api"
Requires-Dist: pydantic (>=2.0,<3.0)
Requires-Dist: uvicorn (>=0.20) ; extra == "api"
Project-URL: Homepage, https://github.com/tomasgonz/worldcountrygroups
Project-URL: Repository, https://github.com/tomasgonz/worldcountrygroups
Description-Content-Type: text/markdown

# worldcountrygroups

Query international country groupings (EU, BRICS, G20, NATO, etc.) with 46 built-in group definitions.

## Installation

```bash
pip install worldcountrygroups          # core library only
pip install worldcountrygroups[api]     # with FastAPI server
```

## Python API

```python
import worldcountrygroups

# List all group IDs
worldcountrygroups.list_groups()  # ['acd', 'acp', ..., 'zangger']

# Get a group with full details
group = worldcountrygroups.get_group("brics")
print(group.name)           # "BRICS"
print(group.country_count)  # 5

# Get countries in a group
countries = worldcountrygroups.get_countries("eu")
print(len(countries))       # 27

# Search groups by country, domain, or text
worldcountrygroups.search_groups(country="Brazil")    # groups containing Brazil
worldcountrygroups.search_groups(domain="Africa")     # groups in Africa domain
worldcountrygroups.search_groups(q="european")        # text search
```

## API Server

```bash
worldcountrygroups serve --port 8000
```

### Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/groups` | List all groups (summaries) |
| GET | `/groups/{gid}` | Get full group with countries |
| GET | `/groups/{gid}/countries` | Get countries in a group |
| GET | `/countries/{iso}` | Get group memberships for a country |
| GET | `/search?q=&country=&domain=` | Search groups |

## License

MIT

