fbi-data-api 0.1.0__tar.gz

fbi_data_api-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+__pycache__/
+.pytest_cache/
+.vscode/
+.env

fbi_data_api-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

fbi_data_api-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ted Jesus C. Chua
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fbi_data_api-0.1.0/PKG-INFO

@@ -0,0 +1,54 @@
+Metadata-Version: 2.4
+Name: fbi-data-api
+Version: 0.1.0
+Summary: Interface for extracting data assets from the FBI Crime Data API.
+Project-URL: Homepage, https://github.com/teddythepooh/fbi_api
+Project-URL: Issues, https://github.com/teddythepooh/fbi_api/issues
+Author-email: "Ted Jesus C. Chua" <chuatedjesusc@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Ted Jesus C. Chua
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: pandas>=3.0.1
+Requires-Dist: python-dotenv>=1.2.2
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: requests>=2.32.5
+Description-Content-Type: text/markdown
+
+# FBI Crime Data API
+This is a wrapper around the FBI Crime Data API, the first of its kind as of March 2026.
+
+## Example
+After signing up for an API key in https://api.data.gov/signup/, 
+
+```python
+from fbi_api import FBI
+
+# If no api_key is passed, your environment variable FBI_API_KEY is automatically invoked.
+api = FBI(api_key = your_api_key)
+
+metadata = api.get_metadata(state_abbr = "all")
+
+# ORI stands for Originating Agency Identifer (ORI), uniquely identifying the law enforcement agencies that report
+# to the FBI. The ORIs in a state can be extracted from api.get_metadata().
+crime_statistics = api.get_crime_statistics(ori = "ILCPD0000", year = 2024, offense = "Violent Crimes")
+```

fbi_data_api-0.1.0/README.md

@@ -0,0 +1,18 @@
+# FBI Crime Data API
+This is a wrapper around the FBI Crime Data API, the first of its kind as of March 2026.
+
+## Example
+After signing up for an API key in https://api.data.gov/signup/, 
+
+```python
+from fbi_api import FBI
+
+# If no api_key is passed, your environment variable FBI_API_KEY is automatically invoked.
+api = FBI(api_key = your_api_key)
+
+metadata = api.get_metadata(state_abbr = "all")
+
+# ORI stands for Originating Agency Identifer (ORI), uniquely identifying the law enforcement agencies that report
+# to the FBI. The ORIs in a state can be extracted from api.get_metadata().
+crime_statistics = api.get_crime_statistics(ori = "ILCPD0000", year = 2024, offense = "Violent Crimes")
+```

fbi_data_api-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["hatchling >= 1.26"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/fbi_api"]
+
+[project]
+name = "fbi-data-api"
+version = "0.1.0"
+authors = [
+  { name="Ted Jesus C. Chua", email="chuatedjesusc@gmail.com" },
+]
+description = "Interface for extracting data assets from the FBI Crime Data API."
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "pandas>=3.0.1",
+    "python-dotenv>=1.2.2",
+    "pyyaml>=6.0.3",
+    "requests>=2.32.5",
+]
+license = {file = "LICENSE"}
+license-files = ["LICEN[CS]E*"]
+
+[dependency-groups]
+dev = [
+    "ipykernel>=7.2.0",
+    "pytest>=9.0.2",
+    "pytest-mock>=3.15.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/teddythepooh/fbi_api"
+Issues = "https://github.com/teddythepooh/fbi_api/issues"

fbi_data_api-0.1.0/src/fbi_api/__init__.py

@@ -0,0 +1 @@
+from .core import FBI

fbi_data_api-0.1.0/src/fbi_api/config.yml

@@ -0,0 +1,64 @@
+state_abbrs:
+  - AL
+  - AK
+  - AZ
+  - AR
+  - CA
+  - CO
+  - CT
+  - DE
+  - FL
+  - GA
+  - HI
+  - ID
+  - IL
+  - IN
+  - IA
+  - KS
+  - KY
+  - LA
+  - ME
+  - MD
+  - MA
+  - MI
+  - MN
+  - MS
+  - MO
+  - MT
+  - NE
+  - NV
+  - NH
+  - NJ
+  - NM
+  - NY
+  - NC
+  - ND
+  - OH
+  - OK
+  - OR
+  - PA
+  - RI
+  - SC
+  - SD
+  - TN
+  - TX
+  - UT
+  - VT
+  - VA
+  - WA
+  - WV
+  - WI
+  - WY
+  - DC
+
+offenses:
+  Violent Crimes: V
+  Aggravated Assault: ASS
+  Burglary: BUR
+  Larceny: LAR
+  Motor Vehicle Theft: MVT
+  Homicide: HOM
+  Rape: RPE
+  Robbery: ROB
+  Arson: ARS
+  All Property Crimes: P

fbi_data_api-0.1.0/src/fbi_api/core.py

@@ -0,0 +1,107 @@
+import os
+import requests
+import pandas as pd
+from pathlib import Path
+from .utils import load_yaml
+
+class FBI:
+    base_url = "https://api.usa.gov/crime/fbi/cde"
+    config = load_yaml(Path(__file__).parent.joinpath("config.yml"))
+    
+    def __init__(self, api_key: str = None):
+        '''
+        If no api_key is passed, it is invoked from environment variable "FBI_API_KEY."
+        '''
+        self.api_key = api_key
+
+    @staticmethod
+    def _get_state_abbrs() -> list:
+        return FBI.config["state_abbrs"]
+    
+    @staticmethod
+    def _get_offenses() -> dict:
+        return FBI.config["offenses"]
+        
+    def _get_api_key(self) -> str:
+        return os.getenv("FBI_API_KEY", default = self.api_key)
+    
+    def _add_key_to_call(self, api_call: str) -> str:
+        prefix = "&" if "?" in api_call else "?"
+
+        auth_str = f"{prefix}API_KEY={self._get_api_key()}"
+        
+        if not api_call.endswith(auth_str):
+            api_call = f"{api_call}{auth_str}"
+        
+        return api_call
+    
+    def get(self, api_call: str, timeout_limit: int = 10) -> dict:
+        api_call = self._add_key_to_call(api_call)
+        response = requests.get(api_call, timeout = timeout_limit)
+        
+        return response.json() if response.status_code == 200 else None
+
+    def _oris_by_state(self, state_abbr: str) -> pd.DataFrame:
+        nested = self.get(f"{FBI.base_url}/agency/byStateAbbr/{state_abbr}")
+
+        flattened = []
+
+        for agencies in nested.values():
+            for agency in agencies:
+                flattened.append(agency)
+        
+        return pd.DataFrame(flattened)
+    
+    def get_metadata(self, state_abbr: str) -> pd.DataFrame:
+        '''
+        state_abbr: State abbreviation of desired state.
+        
+        Extracts the metadata for a state, namely all law enforcement agencies that have provided data to the 
+        Uniform Crime Reporting (UCR) program. If metadata for all states are desired, set state_abbr to "all."
+        '''
+        if state_abbr == "all":
+            results = []
+            
+            for state in FBI._get_state_abbrs():
+                print(f"Extracting metadata for {state}...")
+                results.append(self._oris_by_state(state))
+                
+            return pd.concat(results, ignore_index = True)
+        else:
+            return self._oris_by_state(state_abbr)
+    
+    def get_crime_statistics(self, ori: str, year: int, offense: str) -> pd.DataFrame:
+        '''
+        ori: The originating agency identifier (ORI). Invoke get_metadata() to extract all ORIs in a state.
+        year: The year.
+        
+        Extracts the monthly crime statistics reported by an agency.
+        '''
+        try:
+            offense_mapping = FBI._get_offenses()[offense]
+            api_call = self.get(
+                f"{FBI.base_url}/summarized/agency/{ori}/{offense_mapping}?from=01-{year}&to=12-{year}"
+                )
+        except KeyError:
+            raise KeyError(f"Valid offenses to pass are {", ".join(list(FBI._get_offenses().keys()))}.")
+    
+        last_refresh_date = api_call["cde_properties"]["last_refresh_date"]["UCR"]
+        
+        _, first_value = next(iter(api_call["offenses"]["actuals"].items()))
+
+        crime_statistics = pd.Series(first_value, name = "count").rename_axis("date").reset_index()
+        
+        month_year_columns = ["month", "year"]
+        crime_statistics[month_year_columns] = crime_statistics["date"].str.split("-", expand = True)
+        crime_statistics.drop(columns = "date", inplace = True)
+        
+        crime_statistics["ori"] = ori
+        crime_statistics["offense"] = offense
+        crime_statistics["last_refresh_date"] = last_refresh_date
+        
+        for col in month_year_columns:
+            crime_statistics[col] = crime_statistics[col].astype(int)
+            
+        crime_statistics.sort_values(by = month_year_columns, inplace = True)
+        
+        return crime_statistics[["ori", "month", "year", "offense", "count", "last_refresh_date"]]

fbi_data_api-0.1.0/src/fbi_api/utils.py

@@ -0,0 +1,9 @@
+import yaml
+from pathlib import Path
+
+def load_yaml(file: Path) -> dict:
+    try:
+        with open(file, "r") as file:
+            return yaml.safe_load(file)
+    except FileNotFoundError:
+        raise FileNotFoundError(f"{file} not found.")

fbi_data_api-0.1.0/tests/data/mock_response_get_crime_statistics.json

@@ -0,0 +1,254 @@
+{
+  "offenses": {
+    "rates": {
+      "Illinois Offenses": {
+        "01-2024": 20.9,
+        "02-2024": 21.92,
+        "03-2024": 23.74,
+        "04-2024": 24.57,
+        "05-2024": 27.94,
+        "06-2024": 27.63,
+        "07-2024": 28.6,
+        "08-2024": 26.73,
+        "09-2024": 25.08,
+        "10-2024": 23.7,
+        "11-2024": 22.51,
+        "12-2024": 20.95
+      },
+      "Illinois Clearances": {
+        "01-2024": 5.35,
+        "02-2024": 5.98,
+        "03-2024": 6.29,
+        "04-2024": 6.24,
+        "05-2024": 7.11,
+        "06-2024": 7.28,
+        "07-2024": 6.97,
+        "08-2024": 6.44,
+        "09-2024": 6.41,
+        "10-2024": 6.72,
+        "11-2024": 5.84,
+        "12-2024": 6.01
+      },
+      "United States Offenses": {
+        "01-2024": 27.87,
+        "02-2024": 26.74,
+        "03-2024": 29.35,
+        "04-2024": 30.06,
+        "05-2024": 33.28,
+        "06-2024": 32.68,
+        "07-2024": 33.04,
+        "08-2024": 31.94,
+        "09-2024": 31.31,
+        "10-2024": 30.54,
+        "11-2024": 27.56,
+        "12-2024": 30.26
+      },
+      "United States Clearances": {
+        "01-2024": 12.52,
+        "02-2024": 12.43,
+        "03-2024": 13.46,
+        "04-2024": 13.44,
+        "05-2024": 14.48,
+        "06-2024": 13.77,
+        "07-2024": 14.49,
+        "08-2024": 13.96,
+        "09-2024": 13.41,
+        "10-2024": 13.55,
+        "11-2024": 12.18,
+        "12-2024": 12.06
+      },
+      "Chicago Police Department Offenses": {
+        "01-2024": 40.47,
+        "02-2024": 39.6,
+        "03-2024": 42.29,
+        "04-2024": 42.52,
+        "05-2024": 49.19,
+        "06-2024": 51.69,
+        "07-2024": 54.88,
+        "08-2024": 48.09,
+        "09-2024": 47.37,
+        "10-2024": 43.54,
+        "11-2024": 41.31,
+        "12-2024": 38.88
+      },
+      "Chicago Police Department Clearances": {
+        "01-2024": 3.52,
+        "02-2024": 3.49,
+        "03-2024": 4.09,
+        "04-2024": 4.17,
+        "05-2024": 4.43,
+        "06-2024": 5.72,
+        "07-2024": 5.38,
+        "08-2024": 3.6,
+        "09-2024": 3.98,
+        "10-2024": 4.51,
+        "11-2024": 4.36,
+        "12-2024": 4.06
+      }
+    },
+    "actuals": {
+      "Chicago Police Department Offenses": {
+        "01-2024": 1068,
+        "02-2024": 1045,
+        "03-2024": 1116,
+        "04-2024": 1122,
+        "05-2024": 1298,
+        "06-2024": 1364,
+        "07-2024": 1448,
+        "08-2024": 1269,
+        "09-2024": 1250,
+        "10-2024": 1149,
+        "11-2024": 1090,
+        "12-2024": 1026
+      },
+      "Chicago Police Department Clearances": {
+        "01-2024": 93,
+        "02-2024": 92,
+        "03-2024": 108,
+        "04-2024": 110,
+        "05-2024": 117,
+        "06-2024": 151,
+        "07-2024": 142,
+        "08-2024": 95,
+        "09-2024": 105,
+        "10-2024": 119,
+        "11-2024": 115,
+        "12-2024": 107
+      }
+    }
+  },
+  "tooltips": {
+    "leftYAxisHeaders": {
+      "yAxisHeaderRates": "Offenses per 100,000 people",
+      "yAxisHeaderActual": "Offenses"
+    },
+    "Percent of Population Coverage": {
+      "Illinois": {
+        "01-2024": 93.46,
+        "02-2024": 93.49,
+        "03-2024": 93.31,
+        "04-2024": 93.28,
+        "05-2024": 93.63,
+        "06-2024": 94.32,
+        "07-2024": 94.23,
+        "08-2024": 94.23,
+        "09-2024": 94.32,
+        "10-2024": 94.29,
+        "11-2024": 94.31,
+        "12-2024": 94.17
+      },
+      "United States": {
+        "01-2024": 95.8,
+        "02-2024": 95.72,
+        "03-2024": 95.61,
+        "04-2024": 95.67,
+        "05-2024": 95.53,
+        "06-2024": 95.73,
+        "07-2024": 95.69,
+        "08-2024": 95.69,
+        "09-2024": 95.62,
+        "10-2024": 95.63,
+        "11-2024": 95.43,
+        "12-2024": 95.47
+      }
+    }
+  },
+  "populations": {
+    "population": {
+      "Illinois": {
+        "01-2024": 12710158,
+        "02-2024": 12710158,
+        "03-2024": 12710158,
+        "04-2024": 12710158,
+        "05-2024": 12710158,
+        "06-2024": 12710158,
+        "07-2024": 12710158,
+        "08-2024": 12710158,
+        "09-2024": 12710158,
+        "10-2024": 12710158,
+        "11-2024": 12710158,
+        "12-2024": 12710158
+      },
+      "United States": {
+        "01-2024": 343551384,
+        "02-2024": 343551384,
+        "03-2024": 343551384,
+        "04-2024": 343551384,
+        "05-2024": 343551384,
+        "06-2024": 343551384,
+        "07-2024": 343551384,
+        "08-2024": 343551384,
+        "09-2024": 343551384,
+        "10-2024": 343551384,
+        "11-2024": 343551384,
+        "12-2024": 343551384
+      },
+      "Chicago Police Department": {
+        "01-2024": 2638698,
+        "02-2024": 2638698,
+        "03-2024": 2638698,
+        "04-2024": 2638698,
+        "05-2024": 2638698,
+        "06-2024": 2638698,
+        "07-2024": 2638698,
+        "08-2024": 2638698,
+        "09-2024": 2638698,
+        "10-2024": 2638698,
+        "11-2024": 2638698,
+        "12-2024": 2638698
+      }
+    },
+    "participated_population": {
+      "Illinois": {
+        "01-2024": 11879491,
+        "02-2024": 11882231,
+        "03-2024": 11859958,
+        "04-2024": 11855607,
+        "05-2024": 11901138,
+        "06-2024": 11988464,
+        "07-2024": 11976528,
+        "08-2024": 11976668,
+        "09-2024": 11987763,
+        "10-2024": 11984867,
+        "11-2024": 11987090,
+        "12-2024": 11969280
+      },
+      "United States": {
+        "01-2024": 329131831,
+        "02-2024": 328851436,
+        "03-2024": 328468916,
+        "04-2024": 328689276,
+        "05-2024": 328179474,
+        "06-2024": 328886364,
+        "07-2024": 328753597,
+        "08-2024": 328739752,
+        "09-2024": 328501661,
+        "10-2024": 328543145,
+        "11-2024": 327838575,
+        "12-2024": 327975212
+      },
+      "Chicago Police Department": {
+        "01-2024": 2638698,
+        "02-2024": 2638698,
+        "03-2024": 2638698,
+        "04-2024": 2638698,
+        "05-2024": 2638698,
+        "06-2024": 2638698,
+        "07-2024": 2638698,
+        "08-2024": 2638698,
+        "09-2024": 2638698,
+        "10-2024": 2638698,
+        "11-2024": 2638698,
+        "12-2024": 2638698
+      }
+    }
+  },
+  "cde_properties": {
+    "max_data_date": {
+      "UCR": "02/2026"
+    },
+    "last_refresh_date": {
+      "UCR": "02/15/2026"
+    }
+  }
+}

fbi_data_api-0.1.0/tests/data/mock_response_get_metadata.json

@@ -0,0 +1,54 @@
+{
+  "LEE": [
+    {
+      "ori": "IL0520200",
+      "counties": "LEE",
+      "is_nibrs": true,
+      "latitude": 41.713726,
+      "longitude": -89.33026,
+      "state_abbr": "IL",
+      "state_name": "Illinois",
+      "agency_name": "Amboy Police Department",
+      "agency_type_name": "City",
+      "nibrs_start_date": "2022-12-01"
+    },
+    {
+      "ori": "IL0520400",
+      "counties": "LEE",
+      "is_nibrs": false,
+      "latitude": 41.747442,
+      "longitude": -89.299351,
+      "state_abbr": "IL",
+      "state_name": "Illinois",
+      "agency_name": "Franklin Grove Police Department",
+      "agency_type_name": "City",
+      "nibrs_start_date": null
+    }
+  ],
+  "BOND": [
+    {
+      "ori": "IL0030300",
+      "counties": "BOND",
+      "is_nibrs": false,
+      "latitude": 38.885924,
+      "longitude": -89.436592,
+      "state_abbr": "IL",
+      "state_name": "Illinois",
+      "agency_name": "Sorento Police Department",
+      "agency_type_name": "City",
+      "nibrs_start_date": null
+    },
+    {
+      "ori": "IL0030100",
+      "counties": "BOND",
+      "is_nibrs": true,
+      "latitude": 38.889313,
+      "longitude": -89.41342,
+      "state_abbr": "IL",
+      "state_name": "Illinois",
+      "agency_name": "Greenville Police Department",
+      "agency_type_name": "City",
+      "nibrs_start_date": "2022-01-01"
+    }
+  ]
+}

fbi_data_api-0.1.0/tests/test_json.py

@@ -0,0 +1,59 @@
+'''
+The underlying API calls in get_metadata() and get_crime_statistics() return nested JSON objects. The tests below verify 
+that they are correctly parsed to a tabular format.
+'''
+import json
+import pytest
+from pathlib import Path
+
+from fbi_api import FBI
+
+def load_mock_json(file: str):
+    try:
+        with open(Path(__file__).parent.joinpath("data").joinpath(file), "r") as file:
+            return json.load(file)
+    except FileNotFoundError:
+        raise FileNotFoundError(f"{file} not found.")
+
+MOCK_RESPONSE_GET_METADATA = load_mock_json("mock_response_get_metadata.json")
+MOCK_RESPONSE_GET_CRIME_STATISTICS = load_mock_json("mock_response_get_crime_statistics.json")
+
+@pytest.fixture(scope = "module")
+def fbi_client():
+    return FBI()
+
+def test_get_metadata(fbi_client, mocker):
+    mocker.patch.object(fbi_client, "get", return_value = MOCK_RESPONSE_GET_METADATA)
+
+    metadata = fbi_client.get_metadata("IL")
+
+    assert set(metadata.columns) == {
+        "ori",
+        "counties",
+        "is_nibrs",
+        "latitude",
+        "longitude",
+        "state_abbr",
+        "state_name",
+        "agency_name",
+        "agency_type_name",
+        "nibrs_start_date"
+        }
+    
+    assert len(metadata) > 0
+
+def test_get_crime_statistics(fbi_client, mocker):
+    mocker.patch.object(fbi_client, "get", return_value = MOCK_RESPONSE_GET_CRIME_STATISTICS)
+
+    crime_statistics = fbi_client.get_crime_statistics(ori = "ILCPD0000", year = 2024, offense = "Violent Crimes")
+
+    assert set(crime_statistics.columns) == {
+        "ori",
+        "month",
+        "year",
+        "offense",
+        "count",
+        "last_refresh_date"
+        }
+    
+    assert len(crime_statistics) > 0