Sample API Call and Tutorial

Crafting an API call is an efficient way to get RegData in a coding environment that will allow the user to immediately interact with that data. In the near future, our API will also support the ability to pull data for more than one jurisdiction, series, or industry at once. Doing so will require the user to have some familiarity with how APIs work. This section gives a brief explanation of how to use the Python library we wrote for the express purpose of enabling Python-literate researchers to interact with our API.

The Python regcensus coding library was written by our team to help users interact with our API in any standard python coding environment using a set of simple functions. Users can install the regcensus library and interact with it in the python environment of their choosing. The get_series, get_jurisdictions, get_periods, get_agencies, and get_industries functions all retrieve ID codes which can then be fed into the get_values function to extract the specified data. Read the regcensus library documentation here for a much more detailed description of these functions.

The sample API call below (made with the regcensus library) demonstrates how a user would pull regulatory restriction count data for the 2019 Alabama regulatory code. Content is displayed using dataframes from the Python pandas library.

The list_series and list_jurisdictions functions both create a python dictionary containing each series and jurisdiction name with its corresponding ID number. Looking at the resulting dictionaries, we can see that the jurisdictionID code for Alberta is 2 and the seriesID code for total restrictions count is 1. We then plug the Alberta jursidictionID into the get_periods function to discover that the years for which Alberta has restriction count data are 2018 and 2019. Finally, we take all of this information and put it into the get_values function to find the data for the factors specified. In this case, we discover that the Alberta regulatory code had 32,883 regulatory restrictions in 2018 and 34,623 restrictions in 2019.

Following the logic set out above, a user interested in making an API call for any give province would first use the list_jurisdictions or get_jurisdictions function to find the jurisdictionID(s) of their chosen province(s) and use the list_series or get_series function to find the seriesID(s) he or she desires. Then, the user would feed the juridictionID(s) into the get_periods function to find the periodCode of the years for which he or she wanted data. More complicated functions such as get_industry follow this same basic logic and can be used to get ID codes that will in turn be fed into the get_values function for more detailed data on those topics. The regcensus library documentation goes into much more detail about these more complicated functions.