Metadata-Version: 2.4
Name: urgentcaremap
Version: 1.0.0
Summary: Python CLI and library for the urgentcaremap.health API — 8,500+ US urgent care clinics
Author: Oleksandr Lorynec
License: MIT
Project-URL: Homepage, https://urgentcaremap.health
Project-URL: Documentation, https://urgentcaremap.health/developers/
Project-URL: Repository, https://github.com/LorynecOleksandr/urgentcaremap-cli
Project-URL: API, https://urgentcaremap.health/api/v1/
Project-URL: Issues, https://github.com/LorynecOleksandr/urgentcaremap-cli/issues
Keywords: urgent-care,healthcare,medical,directory,us,clinics,api
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Healthcare Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# urgentcaremap

[![PyPI](https://img.shields.io/pypi/v/urgentcaremap.svg)](https://pypi.org/project/urgentcaremap/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)

**Python CLI and library** for the free [urgentcaremap.health API](https://urgentcaremap.health/developers/) — **8,500+ US urgent care clinics** across **386 cities**.

> 🌐 Built on data from **[urgentcaremap.health](https://urgentcaremap.health)** — the comprehensive US urgent care directory.

## Install

```bash
pip install urgentcaremap
```

No external dependencies (uses Python stdlib only).

## CLI Quick Start

```bash
# Find urgent cares in a city
urgentcaremap find massachusetts boston

# Find nearest 5 clinics to coordinates
urgentcaremap nearest 42.3467 -71.0972 massachusetts boston

# List all 50 states + DC with clinic counts
urgentcaremap states

# Show site-wide statistics
urgentcaremap stats

# Output as JSON for scripting
urgentcaremap find california los-angeles --json | jq '.[] | .name'
```

## Library Usage

```python
from urgentcaremap_cli import UrgentCareClient

client = UrgentCareClient()

# Get all clinics in a city
clinics = client.find_clinics("massachusetts", "boston")
print(f"Found {len(clinics)} clinics in Boston")

# Find nearest clinics by coordinates
nearest = client.find_nearest(
    lat=42.3467,
    lon=-71.0972,
    state="massachusetts",
    city="boston",
    limit=5,
)
for c in nearest:
    print(f"{c['name']} — {c['distance_km']:.2f} km away")

# Site-wide statistics
stats = client.get_stats()
print(f"Total clinics: {stats['coverage']['total_clinics']}")

# Per-state browsing
ca_cities = client.cities_in_state("california")
networks = client.list_networks()
```

### Available methods

| Method | Description |
|--------|-------------|
| `client.find_clinics(state, city)` | All clinics in a city |
| `client.find_nearest(lat, lon, state, city, limit)` | Nearest by coordinates |
| `client.list_states()` | 50 states + DC with counts |
| `client.list_cities()` | All 386 cities |
| `client.cities_in_state(state)` | Cities in one state |
| `client.list_networks()` | 93+ urgent care networks |
| `client.get_stats()` | Site-wide statistics |
| `client.get_index()` | API metadata |

## Use Cases

- **Telemedicine apps** — refer patients to in-person care
- **Healthcare research** — academic studies on access/density
- **Insurance comparison** — show in-network urgent care
- **Real estate apps** — neighborhood healthcare scoring
- **Chatbots** — answer "where is urgent care nearby?"

## API Reference

Full API documentation: **[urgentcaremap.health/developers/](https://urgentcaremap.health/developers/)**

OpenAPI 3.0 spec: **[urgentcaremap.health/api/openapi.json](https://urgentcaremap.health/api/openapi.json)**

## License

- **Code**: MIT (see [LICENSE](LICENSE))
- **API/Data**: CC-BY-4.0 — attribution required when republishing data

## Citation

If you use this in research or publications:

```bibtex
@misc{urgentcaremap2026,
  author = {Lorynec, Oleksandr},
  title = {UrgentCareMap: US Urgent Care Centers Database},
  year = {2026},
  publisher = {urgentcaremap.health},
  url = {https://urgentcaremap.health}
}
```

## Related projects

- **[urgentcaremap-js](https://github.com/LorynecOleksandr/urgentcaremap-js)** — TypeScript/JavaScript SDK
- **[urgentcaremap-react](https://github.com/LorynecOleksandr/urgentcaremap-react)** — React component library
- **[Open Dataset on Kaggle](https://www.kaggle.com/datasets/urgentcaremap/us-urgent-care-centers)** — Bulk download (CSV/JSON/Parquet)

## Contributing

Pull requests welcome! Please open an issue first to discuss major changes.

---

Built with ❤️ on top of **[urgentcaremap.health](https://urgentcaremap.health)** — the free directory of urgent care clinics across the USA.
