covidcountydata

欢迎使用Covid County Data（CCD）数据库的Python客户端库文档。

安装

Python包索引（pypi）上提供了covidcountydata Python包，可以使用pip进行安装。

pip install covidcountydata

API密钥

我们的数据是免费和开放的，任何人都可以使用（并且始终如此）。当我们的团队同意开始此项目时，我们一致认为这是我们的使命的核心。然而，我们认为了解我们的用户以及他们如何使用这些数据是有用的，原因有两个

1. 它帮助我们关注并改进使用最频繁的数据集。
2. 用户数量（通过活跃的API密钥衡量）是我们用于在讨论额外赠款资金时证明项目有用性的一个指标。

我们感谢所有愿意注册并使用其API密钥与我们数据交互的人。

要注册API密钥，您可以在我们的网站上注册，或使用Python包中的register方法。

from covidcountydata import Client

c = Client()
c.register()

您将被提示输入您的电子邮件地址。在输入有效的电子邮件地址后，我们将发放一个API密钥，将其存储在您的机器上，并自动将其应用于所有未来从Python发送到我们服务器的请求。

如果您任何时候想删除您的API密钥，请删除文件 ~/.covidcountydata/apikey。

数据

数据集

您可以通过Python库查看我们API中可用的数据集列表

from covidcountydata import Client

c = Client()
print(c.datasets)

有关每个数据集的更多信息，我们建议您访问我们的数据文档页面。

数据键

我们数据库中的许多数据集都通过一个或多个常见的“键”进行索引。这些键包括

• vintage：数据被下载到我们数据库的日期和时间。我们收集这个信息是因为COVID-19的快速发展--它使我们能够记录数据何时被更改/纠正/更新。
• dt：与观测值对应的日期和时间。对于像COVID检测这样的系列，这可能是一个日频率，但对于其他像失业这样的系列，可能是一个周或月频率。
• location：位置的地理标识符。对于数据集中的县/州，这个变量对应于联邦信息处理标准编号。

当加载包含共同键的两个系列时，它们将在它们的共同键上合并。

请求数据

使用Python客户端库请求数据涉及三个步骤

1. 创建客户端

要创建客户端，请使用Client类。

from covidcountydata import Client

c = Client()

如果您有一个API密钥，您可以将其作为可选参数传递（请参阅API密钥部分）。

c = Client("my api key")

如果您已在当前机器上注册了API密钥，它将自动为您加载并使用。

在实际操作中，除非您从环境变量或其他来源加载数据，否则很少需要手动传递API密钥。

2. 构建请求

API中的每个数据集都有一个相关的方法。

要将数据集添加到当前请求中，请调用Client.dataset()方法。例如，要将covid_us数据集添加到请求中，您将调用

c.covid_us(state="CA")

如果您还想添加另一个数据集，例如demographics，您只需调用该方法即可。

c.demographics()

您可以通过打印当前客户端来查看客户端的打印形式，以了解当前请求的外观。

print(c)

要清除当前请求，请使用c.reset()。

由于每个数据集都会为客户端构建一个请求并返回客户端本身，因此我们可以将多个请求链接起来。例如，我们可以用以下方法代替上面的单独命令：

c.covid_us(state="CA").demographics()

过滤数据

每个数据集函数都有许多过滤器可以应用。

这些过滤器允许您选择特定的行和/或列。

例如，在上面的例子中，我们有c.covid_us(state="CA")。这指示客户端仅获取位于加利福尼亚州的地域数据。

注意：如果过滤条件传递给请求中的一个数据集，但适用于请求中的其他数据集，则它将应用于所有数据集。

例如，在c.covid_us(state="CA").demographics()中，我们只为covid_us数据集指定了state过滤条件，但当数据被收集时，它也将应用于demographics。

我们这样做是因为我们最终在所有请求数据集上执行内部连接，因此当我们在covid_us中过滤州时，它们也将被过滤在demographics中。

3. 获取数据

要获取数据，请从客户端调用 fetch 方法。

df = c.fetch()

注意，在成功请求之后，客户端会被重置，因此没有“累积”的请求。

示例

我们在README中提供了一些简单的示例，但您也可以在examples文件夹中找到更多示例。

简单示例：所有FIPS的单个数据集

下面的示例加载了县内的所有流动性数据。

import covidcountydata as ccd
c = ccd.Client()

c.mobility_devices()
df = c.fetch()

简单示例：单个县的单个数据集

下面的示例仅加载了德克萨斯州特拉维斯县的 demographic 信息。

请注意，我们可以通过指定 fips 代码来选择特定的地理区域。我们可以对之前列出的任何键执行类似操作。

c = ccd.Client()
c.demographics(location=48453)
df = c.fetch()

简单示例：一个州的所有县的单个数据集

下面的示例仅加载了德克萨斯州所有县的 demographic 信息。

请注意，我们可以通过指定 fips 代码来选择特定的地理区域。我们可以对之前列出的任何键执行类似操作。

c = ccd.Client()
c.demographics(state=48)
df = c.fetch()

简单示例：乔治亚州各县自2020年7月1日以来的COVID数据

下面的示例显示了如何根据州和日期范围进行过滤，仅获取7月1日以来的数据。

c = ccd.Client()
c.covid_us(state="GA", dt=">=2020-07-01")
df = c.fetch()

中级示例：乔治亚州各县自2020年7月1日以来的COVID数据，包含县信息

这是一个与上面相同的示例，但我们还添加了 us_counties 端点。这将导致返回的 DataFrame 包含县名、州名、县面积、县纬度和县经度等信息。

c = ccd.Client()
c.covid_us(state="GA", dt=">=2020-07-01").us_counties()
df = c.fetch()

中级示例：单个县的多数据集

下面的示例加载了 COVID 和 demographic 数据，展示了如何将多个数据集的调用链式调用。它将自动合并并返回这些数据集。

注意，对任何数据集（在本例中为 fips=6037）应用筛选器将应用到所有数据集。

c = ccd.Client()
(
    c
    .covid_us(location=6037)
    .demographics()
)
df = c.fetch()

高级示例：具有多个筛选器和变量选择的多数据集

下面的示例从三个数据集中加载特定 FIPS 代码的数据，使用特定的 demographic 日期，并从数据集中选择某些变量。

c = ccd.Client()
(
    c
    .economic_snapshots(variable="GDP_All industry total")
    .covid_us(location=6037)
    .demographics(variable="Total population")
)
df = c.fetch()

在 covidcountydata/examples.py 文件中还有更多示例。我们鼓励您探索它们，并在有问题时与我们联系！