FCC Clearinghouse API Python SDK

A Python SDK for the FCC's Clearinghouse API

FCC API Information

FCC API Developer Guide

Installation

Change to clearinghouse-1.0 directory

$ [sudo] python setup.py install

Usage

API Key

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

API Python Classes

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.

Usage Examples

Search for Features Example

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)

API Call XML Example

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)

ClearinghouseStoredValue Methods

getResponseURL()

• Returns the URL that was used by the ClearinghouseAPI object

getResponseData()

• Returns a string of the response data in its current format

getResponseFormat()

• Returns the response format that was used by the ClearinghouseAPI object

ClearinghouseAPI Methods

retrieveAPIData(apiName, **args)

• 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

searchForFeatures(searchString)

• 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

searchForDevices(searchString)

• 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)

listOfMobileDevices()

• 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

deviceDetails(deviceId)

• 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

setParams(**args)

• 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)

getCurrentParams()

• Returns a dictionary of current parameters and their values

getParam(toGet)

• Returns the value of the specified parameter
• Required parameter: toGet (parameter name as string value)
• Example: myClearinghouse.getParam('rowPerPage')

API Names for retrieveAPIData() method

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

API Parameters

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