policy-design-lab · ylyangtw · Jul 31, 2025 · Jun 30, 2025 · Jul 29, 2025 · Jul 30, 2025
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.24.0] - 2025-07-31
+
+### Changed
+- Rename totalCounts with totalRecipientCount. [#334](https://github.com/policy-design-lab/pdl-api/issues/334)
+- Update Title I endpoints to include data from 2014 to 2023. [#192](https://github.com/policy-design-lab/pdl-api/issues/192)
+
 ## [0.23.0] - 2025-06-26
 
 ### Added
@@ -241,6 +247,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 - Open API specification file. [#50](https://github.com/policy-design-lab/pdl-api/issues/50)
 
+[0.24.0]: https://github.com/policy-design-lab/pdl-api/compare/0.23.0...0.24.0
 [0.23.0]: https://github.com/policy-design-lab/pdl-api/compare/0.22.0...0.23.0
 [0.22.0]: https://github.com/policy-design-lab/pdl-api/compare/0.21.0...0.22.0
 [0.21.0]: https://github.com/policy-design-lab/pdl-api/compare/0.20.0...0.21.0

diff --git a/Dockerfile b/Dockerfile
@@ -1,6 +1,6 @@
 FROM python:3.9-slim
 
-ENV POETRY_VIRTUALENVS_CREATE false
+ENV POETRY_VIRTUALENVS_CREATE=false
 
 RUN apt update \
     && apt upgrade -y \
@@ -29,7 +29,7 @@ ENV DB_HOST=localhost \
     ALL_PROGRAMS_START_YEAR=2018 \
     ALL_PROGRAMS_END_YEAR=2022 \
     TITLE_I_START_YEAR=2014 \
-    TITLE_I_END_YEAR=2021 \
+    TITLE_I_END_YEAR=2023 \
     TITLE_II_START_YEAR=2014 \
     TITLE_II_END_YEAR=2023 \
     CROP_INSURANCE_START_YEAR=2014 \

diff --git a/app/controllers/configs.py b/app/controllers/configs.py
@@ -34,7 +34,7 @@ class to list all configuration settings required for preprocessing and formatti
     ALL_PROGRAMS_END_YEAR = int(os.getenv('ALL_PROGRAMS_END_YEAR', '2022'))  # Landing Page endpoint
 
     TITLE_I_START_YEAR = int(os.getenv('TITLE_I_START_YEAR', '2014'))
-    TITLE_I_END_YEAR = int(os.getenv('TITLE_I_END_YEAR', '2021'))
+    TITLE_I_END_YEAR = int(os.getenv('TITLE_I_END_YEAR', '2023'))
 
     TITLE_II_START_YEAR = int(os.getenv('TITLE_II_START_YEAR', '2014'))
     TITLE_II_END_YEAR = int(os.getenv('TITLE_II_END_YEAR', '2023'))

diff --git a/app/controllers/pdl.py b/app/controllers/pdl.py
@@ -214,13 +214,21 @@ def titles_title_i_summary_search():
     min_year, max_year = cfg.TITLE_I_START_YEAR, cfg.TITLE_I_END_YEAR
     start_year = request.args.get('start_year', type=int, default=min_year)
     end_year = request.args.get('end_year', type=int, default=max_year)
-    title_id = 100
+
+    title_id = get_title_id(TITLE_I_NAME)
+    if title_id is None:
+        msg = {
+            "reason": "No record for the given title name " + TITLE_I_NAME,
+            "error": "Not found: " + request.url,
+        }
+        logging.error("Title I: " + json.dumps(msg))
+        return rs_handlers.not_found(msg)
 
     if start_year and end_year and start_year > end_year:
         start_year, end_year = min_year, max_year  # Return all data if invalid range
 
     if start_year is None:
-        start_year = min_year  # Default to earliest available year
+        start_year = min_year  # Default to the earliest available year
 
     if end_year is None:
         end_year = max_year  # Default to latest available year
@@ -234,13 +242,21 @@ def titles_title_i_state_distribution_search():
     min_year, max_year = cfg.TITLE_I_START_YEAR, cfg.TITLE_I_END_YEAR
     start_year = request.args.get('start_year', type=int, default=min_year)
     end_year = request.args.get('end_year', type=int, default=max_year)
-    title_id = 100
+
+    title_id = get_title_id(TITLE_I_NAME)
+    if title_id is None:
+        msg = {
+            "reason": "No record for the given title name " + TITLE_I_NAME,
+            "error": "Not found: " + request.url,
+        }
+        logging.error("Title I: " + json.dumps(msg))
+        return rs_handlers.not_found(msg)
 
     if start_year and end_year and start_year > end_year:
         start_year, end_year = min_year, max_year  # Reset to full range if invalid
 
     if start_year is None:
-        start_year = min_year  # Default to earliest available year
+        start_year = min_year  # Default to the earliest available year
 
     if end_year is None:
         end_year = max_year  # Default to latest available year
@@ -283,7 +299,7 @@ def titles_title_i_subtitles_subtitle_a_state_distribution_search():
         start_year, end_year = min_year, max_year  # Reset to full range if invalid
 
     if start_year is None:
-        start_year = min_year  # Default to earliest available year
+        start_year = min_year  # Default to the earliest available year
 
     if end_year is None:
         end_year = max_year  # Default to latest available year
@@ -311,7 +327,7 @@ def titles_title_i_subtitles_subtitle_a_summary_search():
         start_year, end_year = min_year, max_year  # Reset to full range if invalid
 
     if start_year is None:
-        start_year = min_year  # Default to earliest available year
+        start_year = min_year  # Default to the earliest available year
 
     if end_year is None:
         end_year = max_year  # Default to latest available year
@@ -339,7 +355,7 @@ def titles_title_i_subtitles_subtitle_d_state_distribution_search():
         start_year, end_year = min_year, max_year  # Reset to full range if invalid
 
     if start_year is None:
-        start_year = min_year  # Default to earliest available year
+        start_year = min_year  # Default to the earliest available year
 
     if end_year is None:
         end_year = max_year  # Default to latest available year
@@ -367,7 +383,7 @@ def titles_title_i_subtitles_subtitle_d_summary_search():
         start_year, end_year = min_year, max_year  # Reset to full range if invalid
 
     if start_year is None:
-        start_year = min_year  # Default to earliest available year
+        start_year = min_year  # Default to the earliest available year
 
     if end_year is None:
         end_year = max_year  # Default to latest available year
@@ -395,7 +411,7 @@ def titles_title_i_subtitles_subtitle_e_state_distribution_search():
         start_year, end_year = min_year, max_year  # Reset to full range if invalid
 
     if start_year is None:
-        start_year = min_year  # Default to earliest available year
+        start_year = min_year  # Default to the earliest available year
 
     if end_year is None:
         end_year = max_year  # Default to latest available year
@@ -423,7 +439,7 @@ def titles_title_i_subtitles_subtitle_e_summary_search():
         start_year, end_year = min_year, max_year  # Reset to full range if invalid
 
     if start_year is None:
-        start_year = min_year  # Default to earliest available year
+        start_year = min_year  # Default to the earliest available year
 
     if end_year is None:
         end_year = max_year  # Default to latest available year
@@ -1441,7 +1457,7 @@ def generate_title_iv_state_distribution_response(program_id, start_year, end_ye
         Program.name.label('programName'),
         Payment.year.label('year'),
         Payment.payment.label('totalPaymentInDollars'),
-        Payment.recipient_count.label('totalCounts')
+        Payment.recipient_count.label('totalRecipientCount')
     ).join(
         Program, Payment.program_id == Program.id
     ).filter(
@@ -1575,7 +1591,7 @@ def generate_title_i_total_state_distribution_response(title_id, start_year, end
         Subtitle.name.label('subtitleName'),
         Payment.year.label('year'),
         Payment.payment.label('totalPaymentInDollars'),
-        Payment.recipient_count.label('totalCounts')).join(
+        Payment.recipient_count.label('totalRecipientCount')).join(
         Subtitle, Payment.subtitle_id == Subtitle.id).filter(
         Payment.title_id == title_id,
         Payment.year.between(start_year, end_year)
@@ -1586,21 +1602,21 @@ def generate_title_i_total_state_distribution_response(title_id, start_year, end
 
     # create a nested dictionary to store data by year and state
     data_by_year_and_state = defaultdict(
-        lambda: defaultdict(lambda: {'totalPaymentInDollars': 0, 'totalRecipients': 0}))
-    all_years_summary = defaultdict(lambda: {'totalPaymentInDollars': 0, 'totalRecipients': 0})
+        lambda: defaultdict(lambda: {'totalPaymentInDollars': 0, 'totalRecipientCount': 0}))
+    all_years_summary = defaultdict(lambda: {'totalPaymentInDollars': 0, 'totalRecipientCount': 0})
 
     for record in result:
         state, title_name, year, payments, recipients = record
         entry = data_by_year_and_state[year][state]
         entry['state'] = state
         entry['totalPaymentInDollars'] += payments
-        entry['totalRecipients'] += recipients
+        entry['totalRecipientCount'] += recipients
 
         # add to all years summary
         summary = all_years_summary[state]
         summary['state'] = state
         summary['totalPaymentInDollars'] += payments
-        summary['totalRecipients'] += recipients
+        summary['totalRecipientCount'] += recipients
 
     # sort by total payment
     sorted_data_by_year = {}
@@ -1701,7 +1717,7 @@ def generate_title_i_total_summary_response(title_id, start_year, end_year):
         Title.name.label('titleName'),
         Payment.year.label('year'),
         Payment.payment.label('totalPaymentInDollars'),
-        Payment.recipient_count.label('totalCounts'),
+        Payment.recipient_count.label('totalRecipientCount'),
         Subtitle.name.label('subtitleName')
     ).join(
         Title, Payment.title_id == Title.id
@@ -1718,25 +1734,25 @@ def generate_title_i_total_summary_response(title_id, start_year, end_year):
     # Initialize dictionaries to store aggregated data
     title_summary = defaultdict(lambda: {
         'totalPaymentInDollars': 0,
-        'totalCounts': 0,
+        'totalRecipientCount': 0,
         'recipients': [],
         'subtitles': defaultdict(lambda: {
             'totalPaymentInDollars': 0,
-            'totalCounts': 0,
+            'totalRecipientCount': 0,
             'recipients': []
         })
     })
 
     # Process each record in the data
     for state, title_name, year, payment, recipients, subtitle in results:
         title_summary[title_name]['totalPaymentInDollars'] += payment
-        title_summary[title_name]['totalCounts'] += recipients
+        title_summary[title_name]['totalRecipientCount'] += recipients
         title_summary[title_name]['recipients'].append(recipients)
 
         # Aggregate subtitle data
         subtitle_dict = title_summary[title_name]['subtitles'][subtitle]
         subtitle_dict['totalPaymentInDollars'] += payment
-        subtitle_dict['totalCounts'] += recipients
+        subtitle_dict['totalRecipientCount'] += recipients
         subtitle_dict['recipients'].append(recipients)
 
     # Prepare the final summary
@@ -1754,16 +1770,18 @@ def generate_title_i_total_summary_response(title_id, start_year, end_year):
             subtitle_list.append({
                 'programName': subtitle_name,
                 'totalPaymentInDollars': round(subtitle_info['totalPaymentInDollars'], 2),
-                'totalCounts': subtitle_info['totalCounts'],
+                'totalRecipientCount': subtitle_info['totalRecipientCount'],
                 'averageRecipientCount': subtitle_avg_recipients,
                 'totalPaymentInPercentage': round(payment_percentage, 2)
             })
 
         title_entry = {
             'titleName': title,
             'totalPaymentInDollars': round(info['totalPaymentInDollars'], 2),
-            'totalCounts': info['totalCounts'],
+            'totalRecipientCount': info['totalRecipientCount'],
             'averageRecipientCount': round(average_recipient_count, 2),
+            'startYear': start_year,
+            'endYear': end_year,
             'subtitles': subtitle_list
         }
         final_summary.append(title_entry)
@@ -1847,7 +1865,7 @@ def generate_title_i_state_distribution_response(subtitle_id, start_year, end_ye
         func.sum(Payment.payment).label('totalPaymentInDollars'),
         func.round(func.avg(Payment.base_acres), 2).label('averageAreaInAcres'),
         func.cast(func.avg(Payment.recipient_count), BigInteger).label('averageRecipientCount'),
-        func.cast(func.sum(Payment.recipient_count), Integer).label('totalCounts'),
+        func.cast(func.sum(Payment.recipient_count), Integer).label('totalRecipientCount'),
         (func.cast(func.sum(Payment.recipient_count) / subtitle_subquery_recipient_count * 100, Numeric(5, 2))).label(
             'averageRecipientCountInPercentageNationwide')
     ).join(
@@ -1872,7 +1890,7 @@ def generate_title_i_state_distribution_response(subtitle_id, start_year, end_ye
         response_dict = dict(zip(column_names, row))
 
         # Cleanup / renaming attributes
-        response_dict["totalCountsInPercentageNationwide"] = response_dict["averageRecipientCountInPercentageNationwide"]
+        response_dict["totalRecipientCountInPercentageNationwide"] = response_dict["averageRecipientCountInPercentageNationwide"]
         if response_dict['averageAreaInAcres'] is None:
             response_dict['averageAreaInAcres'] = 0.0
         subtitle_response_dict[response_dict['state']] = response_dict
@@ -1908,7 +1926,7 @@ def generate_title_i_state_distribution_response(subtitle_id, start_year, end_ye
             Payment.state_code.label('state'),
             Program.name.label('programName'),
             func.sum(Payment.payment).label('totalPaymentInDollars'),
-            func.cast(func.sum(Payment.recipient_count), Integer).label('totalCounts'),
+            func.cast(func.sum(Payment.recipient_count), Integer).label('totalRecipientCount'),
             func.round(func.avg(Payment.base_acres), 2).label('averageAreaInAcres'),
             func.cast(func.sum(Payment.recipient_count) / total_years, BigInteger).label('averageRecipientCount'),
             (func.cast(func.sum(Payment.payment) / program_subquery_total_payment * 100, Numeric(5, 2))).label(
@@ -1938,7 +1956,7 @@ def generate_title_i_state_distribution_response(subtitle_id, start_year, end_ye
             state = response_dict['state']
 
             # Cleanup / renaming attributes
-            response_dict["totalCountsInPercentageNationwide"] = response_dict[
+            response_dict["totalRecipientCountInPercentageNationwide"] = response_dict[
                 "averageRecipientCountInPercentageNationwide"]
             response_dict['subPrograms'] = []
             if response_dict['averageAreaInAcres'] is None:
@@ -2020,14 +2038,14 @@ def generate_title_i_state_distribution_response(subtitle_id, start_year, end_ye
                 else:
                     program["totalPaymentInPercentageWithinState"] = 0.0
 
-                if subtitle_response_dict[state]["totalCounts"] != 0:
-                    program["totalCountsInPercentageWithinState"] = (
-                        round(program["totalCounts"] / subtitle_response_dict[state]["totalCounts"] * 100, 2))
+                if subtitle_response_dict[state]["totalRecipientCount"] != 0:
+                    program["totalRecipientCountInPercentageWithinState"] = (
+                        round(program["totalRecipientCount"] / subtitle_response_dict[state]["totalRecipientCount"] * 100, 2))
                     # TODO: Temporary fix. The below attribute may need to be calculated based on the average recipient count or removed if not needed.
-                    program["averageRecipientCountInPercentageWithinState"] = program["totalCountsInPercentageWithinState"]
+                    program["averageRecipientCountInPercentageWithinState"] = program["totalRecipientCountInPercentageWithinState"]
                 else:
                     program["averageRecipientCountInPercentageWithinState"] = 0.0
-                    program["totalCountsInPercentageWithinState"] = 0.0
+                    program["totalRecipientCountInPercentageWithinState"] = 0.0
 
                 for subprogram in program["subPrograms"]:
                     if subtitle_response_dict[state]["totalPaymentInDollars"] != 0.0:
@@ -2060,7 +2078,7 @@ def generate_title_i_summary_response(subtitle_id, start_year, end_year):
     subtitle_query = (session.query(
         Subtitle.name.label('subtitleName'),
         func.sum(Payment.payment).label('totalPaymentInDollars'),
-        func.cast(func.sum(Payment.recipient_count), Integer).label('totalCounts'),
+        func.cast(func.sum(Payment.recipient_count), Integer).label('totalRecipientCount'),
         func.cast(subtitle_avg_recipient_count, BigInteger).label('averageRecipientCount')
     ).join(
         Subtitle, Payment.subtitle_id == Subtitle.id
@@ -2080,6 +2098,8 @@ def generate_title_i_summary_response(subtitle_id, start_year, end_year):
     subtitle_response_dict = dict()
     for row in subtitle_result:
         subtitle_response_dict = dict(zip(column_names, row))
+        subtitle_response_dict["startYear"] = start_year
+        subtitle_response_dict["endYear"] = end_year
         subtitle_response_dict["programs"] = []
 
     # Find all programs under the subtitle
@@ -2111,7 +2131,7 @@ def generate_title_i_summary_response(subtitle_id, start_year, end_year):
         program_query = (session.query(
             Program.name.label('programName'),
             func.sum(Payment.payment).label('totalPaymentInDollars'),
-            func.cast(func.sum(Payment.recipient_count), Integer).label('totalCounts'),
+            func.cast(func.sum(Payment.recipient_count), Integer).label('totalRecipientCount'),
             func.cast(program_avg_recipient_count, BigInteger).label('averageRecipientCount'),
             (func.cast(func.sum(Payment.payment) / subtitle_subquery * 100, Numeric(5, 2))).label(
                 'totalPaymentInPercentage')

diff --git a/pyproject.toml b/pyproject.toml
@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "pdl-api"
-version = "0.23.0"
+version = "0.24.0"
 description = ""
 authors = ["Yong Wook Kim <ywkim@illinois.edu>"]
 readme = "README.md"