A Python SDK for the FCC's Clearinghouse API
Change to clearinghouse-1.0 directory
$ [sudo] python setup.py install
Before using the SDK, a user must obtain an API key. The API key is free, as is the data, and instructions for obtaining an API key can be found at http://apps.fcc.gov/accessibilityclearinghouse/developers.html?pgID=5
The SDK provides two classes for retrieving data from the FCC Clearinghouse APIs and storing the data.
The ClearinghouseAPI class provides several methods that allow the user to search for devices, manufacturers, brands, or device features. The class also provides a method that allows the user to access any of the Clearinghouse APIs. The ClearinghouseStoredValue class stores the URL that was used for the request, the format type of the retrieved data (xml, json, or jsonp), and a string of the data.
from clearinghouse.clearinghouse_api import ClearinghouseAPI
# create instance of ClearinghouseAPI, pass in API key (str) as parameter
myClearinghouse = ClearinghouseAPI('YOUR API KEY HERE')
# call searchForFeatures method with search string parameter
dictOfFeatures = myClearinghouse.searchForFeatures('adjustable')
print(dictOfFeatures)
from clearinghouse.clearinghouse_api import ClearinghouseAPI
import xml.etree.ElementTree as et
# create instance of ClearinghouseAPI, pass in API key (str) as parameter
myClearinghouse = ClearinghouseAPI('YOUR API KEY HERE')
xmlStoredValue = myClearinghouse.retrieveAPIData('federal contacts')
# print XML if needed
# xmlStoredValue.printData()
xmlContent = et.fromstring(xmlStoredValue.getResponseData())
data = dict()
for contact in xmlContent.findall('Contact'):
contactId = int(contact.find("id").text)
name = str(contact.find("entityName").text)
# get email if it exists
try: email = str(contact.find("generalEmail").text)
except: email = ''
# get fax if it exists
try: fax = str(contact.find("fax").text)
except: fax = ''
# add name, email, and fax to dictionary. Use contactId as key
if contactId not in data:
data[contactId] = (name, email, fax)
print(data)
- Returns the URL that was used by the ClearinghouseAPI object
- Returns a string of the response data in its current format
- Returns the response format that was used by the ClearinghouseAPI object
- Returns a ClearinghouseStoredValue object with a string containing response data in XML, JSON, or JSONP format
- Required parameter: apiName (from valid API name list)
- Optional parameters: any parameter from list of defined parameters. E.g. responseFormat='json'
- Example:
myClearinghouse.retrieveAPIData('search', searchString='apple', responseFormat='json') - Review list of API Names below
- Searches through feature names to find those that contain the search string
- Returns a dictionary of feature IDs and names
- Required parameter: searchString (any string value)
- NOTE: pass "all features" to return a list of all features
- Compares searchString to Brand, Maker, and Model
- Returns a dictionary of device IDs and brand, maker, model, and regions
- Required Parameter: searchString (any string value)
- Returns a dictionary of device IDs and brand, maker, and model OR returns a strings containing raw XML, JSON, or JSONP
- Optional Parameter: responseFormat ('xml', 'json', jsonp') will return a raw string
- Returns a dictionary of device brand, maker, and model along with a list of accessibility features for the device
- Required parameter: deviceId (number) from product list
- Sets a list of parameters to be used in API calls
- Does not return any values
- Optional Parameter: any parameters to update
- Example:
myClearinghouse.setParams(responseFormat='json', disabilityId=5)
- Returns a dictionary of current parameters and their values
- Returns the value of the specified parameter
- Required parameter: toGet (parameter name as string value)
- Example:
myClearinghouse.getParam('rowPerPage')
| Name | Description |
| 'disability types' | Returns a list of disabilities along with the disability type name, id, short description and long description |
| 'mobile devices' | Returns a list of mobile devices as well as the original source of the data |
| 'device details' | Returns a list of accessibility features (with name and description) that are supported by a particular device as well as the source for the original data |
| 'features' | Returns a list of accessibility features (with name and description) that may be supported by various products |
| 'manufacturers' | Returns a list of product manufacturers |
| 'regions' | Returns a list of regions where various products may be available |
| 'search' | Returns a list of mobile devices based on a search query (manufacturer, brand, or model) as well as the original source of the data |
| 'search autocomplete' | Returns a list of mobile devices (manufacturer or brand and model number) as the user types a search query |
| 'apps and technologies' | Returns a list of accessible apps and assistive technologies as well as the original source of the data |
| 'content' | Returns content for Fact Sheets and User Voice questions as well as the original source of the data |
| 'convenience contacts' | Returns a variety of convenience contact information as well as the original source of the data for Service Providers, Equipment Manufacturers, Schools and Universities, and National and International Organizations. The list of contacts can be grouped by state |
| 'states' | Returns a list of states by which the convenience contacts can be grouped |
| 'events' | Returns a list of upcoming and past Disability Related Events |
| 'federal contacts' | Returns a list of Federal Agencies that provide accessibility related services or information |
| 'vpd contacts' | Returns a list of contact information for various Video Programming Distributors |
The following is a list of parameters that can be passed to the setParams() method in order to change the output from the APIs.
NOTE: Parameter names are case sensitive
| Name | Type | Values |
| responseFormat | str | 'xml', 'json', 'jsonp' |
| callback | str | Any string value. Only used for JSONP response format |
| disabilityId | int | 3, 4, 5 ,6, 7 |
| productID | int | Retrieve productID from ClearinghouseAPI for the full list of product IDs |
| feat | int | Retrieve feat from ClearinghouseAPI for the full list of features |
| searchString | str | Any string value |
| limit | int | Value greater than 0. Used to limit number of results for 'search autocomplete' |
| rowPerPage | int | -1 (for all results), 20, 40, 60, 100 |
| page | int | Any value greater than 0 |
| order | str | 'asc', 'desc' |
| mfg | str | Retrieve mfg from ClearinghouseAPI for the full list of manufacturers |
| region | str | Retrieve region from ClearinghouseAPI for the full list of regions |
| entityType | str | Retrieve entityType from ClearinghouseAPI for the full list |
| tag | str | 'vet', 'kid', 'sen' |
| date | str | MM/DD/YYYY format |
| dateFlag | str | 'past', 'future' |
| stateName | str | Retrieve stateName from ClearinghouseAPI for the full list of state names |
| groupByState | Bool | True, False |
| contentType | str | 'Fact sheet', 'UserVoice' |
| vpdType | str | 'broadcaster', 'cable', 'lec', 'satellite', 'other' |
| excel | Bool | True, False. Set to True to receive data in Excel spreadsheet format |