Release 0.4.0 (#21)

* adjustments for v3 of the API

* live url

* v0.4.0

Author: jnelson16

regcensus/__init__.py

@@ -3,6 +3,7 @@
     'get_document_values',
     'get_reading_time',
     'get_series',
+    'get_periods',
     'get_agencies',
     'get_jurisdictions',
     'get_industries',
@@ -21,6 +22,7 @@
     get_document_values,
     get_reading_time,
     get_series,
+    get_periods,
     get_agencies,
     get_jurisdictions,
     get_industries,

regcensus/api.py

@@ -109,7 +109,7 @@ def get_values(series, jurisdiction, date, documentType=None, summary=True,
     # and function returns empty.
     else:
         print("Valid date is required. Select from the following list:")
-        dates = sorted(get_series(jurisdiction)['periodCode'].unique())
+        dates = list_dates(jurisdiction)
         pp.pprint(dates)
         return
 
@@ -182,15 +182,12 @@ def get_reading_time(*args, **kwargs):
     results['footNote'] = (
         'Reading time calculation assumes an 8 hour work-day, '
         'a 5 day work-week, and a 50 week work-year.')
-    return results[[
-        'seriesValue', 'seriesName', 'jurisdictionName', 'periodCode',
-        'sourceCitation', 'sourceName', 'sourceOrganization', 'sourceUrl',
-        'documentationUrl', 'footNote']]
+    return results
 
 
 def get_series(jurisdictionID=None, documentType=None, verbose=0):
     """
-    Get series and date metadata for all or one specific jurisdiction
+    Get series metadata for all or one specific jurisdiction
 
     Args: jurisdictionID (optional): ID for the jurisdiction
 
@@ -202,6 +199,20 @@ def get_series(jurisdictionID=None, documentType=None, verbose=0):
     return clean_columns(json_normalize(requests.get(url_call).json()))
 
 
+def get_periods(jurisdictionID=None, documentType=None, verbose=0):
+    """
+    Get date metadata for all or one specific jurisdiction
+
+    Args: jurisdictionID (optional): ID for the jurisdiction
+
+    Returns: pandas dataframe with the metadata
+    """
+    url_call = periods_url(jurisdictionID, documentType)
+    if verbose:
+        print(f'API call: {url_call}')
+    return clean_columns(json_normalize(requests.get(url_call).json()))
+
+
 def get_agencies(jurisdictionID=None, keyword=None, verbose=0):
     """
     Get metadata for all agencies of a specific jurisdiction
@@ -310,16 +321,16 @@ def list_document_types(jurisdictionID=None):
         for d in json if d["subtypeName"]}.items()))
 
 
-def list_series(jurisdictionID=None):
+def list_series(jurisdictionID=None, documentType=None):
     """
     Args: jurisdictionID (optional): ID for the jurisdiction
 
     Returns: dictionary containing names of series and associated IDs
     """
-    url_call = series_url(jurisdictionID)
+    url_call = series_url(jurisdictionID, documentType)
     json = requests.get(url_call).json()
     return dict(sorted({
-        s["series"]["seriesName"]: s["series"]["seriesID"]
+        s["seriesName"]: s["seriesID"]
         for s in json}.items()))
 
 
@@ -329,7 +340,7 @@ def list_dates(jurisdictionID):
 
     Returns: list of dates available for the jurisdiction
     """
-    return sorted(get_series(jurisdictionID)['periodCode'].unique())
+    return sorted(get_periods(jurisdictionID)['periodCode'].unique())
 
 
 def list_agencies(jurisdictionID=None, keyword=None):
@@ -393,7 +404,21 @@ def list_industries(keyword=None, codeLevel=3, standard='NAICS', onlyID=False):
 
 def series_url(jurisdictionID, documentType=None):
     """Gets url call for series endpoint."""
-    url_call = URL + '/series'
+    url_call = URL + '/dataseries'
+    if jurisdictionID and documentType:
+        url_call += (
+            f'?jurisdiction={jurisdictionID}&'
+            f'documentType={documentType}')
+    elif jurisdictionID:
+        url_call += f'?jurisdiction={jurisdictionID}'
+    elif documentType:
+        url_call += f'?documentType={documentType}'
+    return url_call
+
+
+def periods_url(jurisdictionID, documentType=None):
+    """Gets url call for series endpoint."""
+    url_call = URL + '/seriesperiod'
     if jurisdictionID and documentType:
         url_call += (
             f'?jurisdiction={jurisdictionID}&'

setup.py

@@ -4,7 +4,7 @@
 
 setup(
     name='regcensus',
-    version='0.3.1',
+    version='0.4.0',
     description='Python package for accessing data from the QuantGov API',
     url='https://github.com/QuantGov/regcensus-api-python',
     author='QuantGov',

tests/test_api.py

@@ -15,20 +15,22 @@ def order_results(results, column, descending=False):
 # Tests for get_() functions
 def test_get_series():
     results = rc.get_series(verbose=1)
-    assert order_results(results, 'seriesID') == [1] * 10
+    assert order_results(results, 'seriesID') == [
+        1, 2, 3, 4, 5, 6, 7, 9, 10, 11
+    ]
 
 
 def test_get_agencies():
     results = rc.get_agencies(jurisdictionID=38, verbose=1)
     assert order_results(results, 'agencyID') == [
-        0, 1, 64, 65, 66, 67, 68, 69, 70, 71
+        0, 3, 5, 6, 7, 8, 9, 11, 12, 13
     ]
 
 
 def test_get_agencies_keyword():
     results = rc.get_agencies(keyword='Education', verbose=1)
     assert order_results(results, 'agencyID') == [
-        225, 348, 375, 403, 475, 521, 539, 572, 595, 603
+        52, 216, 225, 226, 238, 267, 285, 296, 356, 358
     ]
 
 
@@ -204,24 +206,25 @@ def test_get_values_country():
 
 
 def test_get_values_agency():
-    results = rc.get_values(series=13, jurisdiction=38, date=2019, agency=195)
-    assert order_results(results, 'seriesValue') == [62.0]
+    results = rc.get_values(series=13, jurisdiction=66, date=2021, agency=3112)
+    assert order_results(results, 'seriesValue') == [40141.0]
 
 
 def test_get_values_all_agencies():
     results = rc.get_values(
-        series=13, jurisdiction=38, date=2019
+        series=13, jurisdiction=66, date=2021
     )
     assert order_results(results, 'seriesValue') == [
-        0.0, 0.0, 1.0, 1.0, 5.0, 18.0, 33.0, 34.0, 50.0, 59.0
+        555.0, 2025.0, 2035.0, 3085.0, 3849.0,
+        4771.0, 5235.0, 5399.0, 6119.0, 6783.0
     ]
 
 
 def test_get_values_multiple_agencies():
     results = rc.get_values(
-        series=13, jurisdiction=38, date=2019, agency=[111, 99]
+        series=13, jurisdiction=66, date=2021, agency=[3112, 3113]
     )
-    assert order_results(results, 'seriesValue') == [34167.0, 91087.0]
+    assert order_results(results, 'seriesValue') == [17304.0, 40141.0]
 
 
 def test_get_values_version():
@@ -233,7 +236,7 @@ def test_get_values_version():
 
 def test_get_values_download():
     results = rc.get_values(
-        series=13, jurisdiction=38, date=2019, agency=195, download='test.csv'
+        series=13, jurisdiction=66, date=2021, agency=3112, download='test.csv'
     )
     assert not results
     assert os.path.exists('test.csv')
@@ -242,27 +245,25 @@ def test_get_values_download():
 
 def test_get_values_incorrect_download(capsys):
     results = rc.get_values(
-        series=13, jurisdiction=38, date=2019, agency=195, download=True
+        series=13, jurisdiction=66, date=2021, agency=3112, download=True
     )
     assert not results
     assert capsys.readouterr().out == 'Valid outpath required to download.\n'
 
 
 def test_get_values_error(capsys):
-    results = rc.get_values(series=1, jurisdiction=38, date=1900, verbose=1)
+    results = rc.get_values(series=1, jurisdiction=38, date=1900)
     assert not results
     assert capsys.readouterr().out == (
-        'API call: https://api.quantgov.org/summary'
-        '?series=1&jurisdiction=38&date=1900\n'
         'WARNING: SeriesValue was not found for the specified parameters. '
         'Please check that you have selected the right combination of '
-        'parameters.  When in doubt, please use the /periods endpoint to find '
-        'out the combinations of series, jurisdiction, periods, agencies, '
-        'document types for which there are data available.{parameters='
-        '{jurisdiction=[US_UNITED_STATES], date=[1900], labelLevel=[3], '
-        'agency=null, dateIsRange=false, filteredOnly=true, label=null, '
-        'series=[SERIES_1], documentType=null, national=false}}\n'
-    )
+        'parameters.  When in doubt, please use the /periods endpoint to '
+        'find out the combinations of series, jurisdiction, periods, '
+        'agencies, document types for which there are data available.'
+        '{parameters={jurisdiction=[US_UNITED_STATES], date=[1900], '
+        'labelLevel=[3], agency=null, dateIsRange=false, filteredOnly=false, '
+        'label=null, series=[SERIES_1], documentType=null, '
+        'national=false, cluster=null}}\n')
 
 
 # Tests for list_() functions
@@ -295,13 +296,14 @@ def test_list_dates():
 
 
 def test_list_agencies():
-    results = rc.list_agencies(jurisdictionID=38)
-    assert results['Administrative Conference of the United States'] == 195
+    results = rc.list_agencies(jurisdictionID=66)
+    assert results['department of health'] == 3112
 
 
 def test_list_agencies_keyword():
     results = rc.list_agencies(keyword='Education')
-    assert results['California Department of Education (California)'] == 770
+    assert results[
+        'california educational facilities authority (California)'] == 2094
 
 
 def test_list_agencies_error(capsys):