Metadata-Version: 2.5
Name: bdcdata
Version: 2.0.0
Summary: Work with FCC Broadband Data Collection (BDC) data in pandas.
Project-URL: Homepage, https://github.com/npappin/bdcdata
Project-URL: Documentation, https://github.com/npappin/bdcdata/tree/main/docs
Project-URL: Issues, https://github.com/npappin/bdcdata/issues
Author-email: "W. Nick Pappin" <nick.pappin@wsu.edu>
Maintainer-email: "W. Nick Pappin" <npappin@gmail.com>
License-Expression: MIT
License-File: LICENSE.txt
Keywords: bdc,broadband,fcc,national broadband map,pandas
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: pandas>=2
Requires-Dist: pyarrow>=12
Requires-Dist: python-dotenv
Requires-Dist: requests>=2.28
Provides-Extra: all
Requires-Dist: pyogrio>=0.7; extra == 'all'
Requires-Dist: tqdm>=4.60; extra == 'all'
Provides-Extra: mobile
Requires-Dist: pyogrio>=0.7; extra == 'mobile'
Provides-Extra: progress
Requires-Dist: tqdm>=4.60; extra == 'progress'
Description-Content-Type: text/markdown

# bdcdata

Work with FCC **Broadband Data Collection** (BDC) data in pandas.

`bdcdata` handles the parts of the National Broadband Map that are tedious to
get right — authentication, the 10-calls-per-minute rate limit, finding the
right file among thousands, unzipping it, and applying the column types from
the FCC's published specification — and hands you a DataFrame.

```python
import bdcdata

bdcdata.set_credentials(username="you@example.com", token="...")

df = bdcdata.availability.fixed(state="WA", technology="fiber")
```

You can write `state="WA"`, `state="Washington"`, or `state=53`, and
`technology="fiber"`, `technology="fttp"`, or `technology=50`. They all mean
the same thing.

## Install

```bash
pip install bdcdata
```

Reading the mobile H3 coverage files means opening a shapefile, which needs an
extra:

```bash
pip install 'bdcdata[mobile]'
```

## Credentials

Every BDC endpoint requires an FCC username and API token, including the
metadata endpoints.

1. Log in at <https://broadbandmap.fcc.gov/login> with your FCC User
   Registration account.
2. Click your username in the top right, then **Manage API Access**.
3. Click **Generate**, accept the terms, and copy the token.

Your username is the email address on the account. Then pick whichever of
these suits you:

```python
bdcdata.set_credentials(username="you@example.com", token="...")
```

```bash
export BDC_USERNAME=you@example.com
export BDC_API_KEY=...
```

```python
# .env file in your working directory, with BDC_USERNAME and BDC_API_KEY
bdcdata.load_dotenv()
```

Check them with `bdcdata.check_credentials()`.

## Documentation

See the [`docs/`](docs/) directory.

## Upgrading from 1.x

**2.0 is a rewrite and the API changed.** See
[docs/migrating-from-v1.md](docs/migrating-from-v1.md).

## License

MIT
