fbi-data-api 0.1.0__py3-none-any.whl

fbi_api/__init__.py

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

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_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_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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+fbi_api/__init__.py,sha256=IszPozU4iZtGN0h_qFTqblBcNh1uY2aeQX9Aq0KXdHs,23
+fbi_api/config.yml,sha256=sA5X2Q3KTaATLnTAjZytFdlOxLO_hqdsWIlFiA1lSi8,630
+fbi_api/core.py,sha256=NsMxAMw-2rh7buEW1vyY_tUWqkOm1X0IFC_z4nBmiTA,4150
+fbi_api/utils.py,sha256=MzDeiVpGUO-jkFKZsQT0fY8-rKnFLMSoi7uV3WSC7D8,253
+fbi_data_api-0.1.0.dist-info/METADATA,sha256=16DYz11kKT20XXlemfUlGdVTJfAQOow8CpymQd-msMw,2476
+fbi_data_api-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+fbi_data_api-0.1.0.dist-info/licenses/LICENSE,sha256=BgOQYYuroNUl_qvYPRK6nS0UPI6R0l2xCs3b6r3CEKA,1095
+fbi_data_api-0.1.0.dist-info/RECORD,,

fbi_data_api-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

fbi_data_api-0.1.0.dist-info/licenses/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.