Merge pull request #4 from QuantGov/documentation_update

Documentation update and documentType option in get_documents()

Author: jnelson16

README.md

@@ -32,23 +32,24 @@ RegCensus API defines a number of periods depending on the series. For example,
 There are six helper functions to retrieve information about these key components of regdata. These functions provider the following information: topics, documents, jurisdictions, series, agencies, and years with data. The list functions begin with __list__. For example, to view the list of topics call __list_topics__. When an topic id parameter is supplied, the function returns the details about a specific topic.
 
 ```
-rc.list_topics()
+rc.list_document_subtype()
 ```
 
-Each topic comprises one or more *series*. The __list_series__ function returns the list of all series when no series id is provided.
+Each subtype comprises one or more *series*. The __list_series__ function returns the list of all series when no series id is provided. This call is a great place to start if you are looking for data based on a **topic** first. 
 
-There are other helper functions that give you a tour around RegData. To see the jurisdictions with data in RegData, call __list_jurisdiction__. This function returns the complete list in a list format. 
 
 ```
 rc.list_jurisdictions(jurisdictionID = 38)
 ```
+Just like the above function call, listing the jurisdictions is another great place to start. If you are looking for data for a specifc jurisdiction(s), this function
+will return the jurisdiction_id for all jurisdiction, which is key for retrieving data on any individual jurisdiction.
 
-The __get_series_period__ function returns a list of all seriesa and the years with data available. 
+The __get_periods__ function returns a list of all seriesa and the years with data available. 
 
 The output from this function can serve as a reference for the valid values that can be passed to parameters in the __get_values__ function. The number of records returned is the unique combination of series and jurisdictions that are available in RegData. The function takes the optional argument jurisdiction id.
 
 ```
-rc.get_series_period(jurisdictionID = 38)
+rc.get_periods(jurisdictionID = 38)
 ```
 
 ## Metadata
@@ -80,6 +81,16 @@ The __get_industries__ function returns a data frame of industries with data in
 rc.get_industries(38)
 ```
 
+### Documents
+
+The __get_documents__ function returns a data frame with metadata for document-level data. The fucntion takes two parameters, jurisdictionID (required) and documentType (default value of 3, which is "all regulations").
+
+The following line will get metadata for documents associated with U.S. Federal healthcare regulations.
+
+```
+rc.get_documents(jurisdictionID = 38, documentType = 1)
+```
+
 ## Values
 
 The __get_values__ function is the primary function for obtaining RegData from the RegCensus API. The function takes the following parameters:

regcensus/api.py

@@ -22,7 +22,7 @@ def get_values(series, jurisdiction, date, filtered=True, summary=True,
         date: Year(s) of data
         summary (optional): Return summary instead of document level data
         filtered (optional): Exclude poorly-performing industry results
-        documentType (optional): Type of document
+        documentType (optional): ID for type of document
         agency (optional): Agency ID
         industry (optional): Industry code using the jurisdiction-specific
             coding system (use 'all' for all industries)
@@ -216,10 +216,21 @@ def get_industries(jurisdictionID):
     return clean_columns(output)
 
 
-def get_documents(jurisdictionID):
+def get_documents(jurisdictionID, documentType=3):
+    """
+    Get metadata for documents available in a specific jurisdiction, optional
+    filtering by document type (see list_document_types() for options)
+
+    Args:
+        jurisdictionID: ID for the jurisdiction
+        documentType (optional): ID for type of document
+
+    Returns: pandas dataframe with the metadata
+    """
     output = pd.io.json.json_normalize(
         requests.get(
-            URL + f'/documents?jurisdiction={jurisdictionID}&documentType=3'
+            URL + (f'/documents?jurisdiction={jurisdictionID}&'
+                   f'documentType={documentType}')
             ).json())
     return clean_columns(output)
 

setup.py

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