Introductory Tutorial
Welcome to the introductory FARA.gov API tutorial. This tutorial is designed for people who aren't familiar with APIs and how to use them. If you already know what an endpoint is and the difference between XML, CSV and JSON, you'll want to visit Endpoints.
What's an API?
API stands for Application Programmer Interface. APIs make it easy for computer programs to request and receive information in a format they can understand.
If you're looking for registant filing data that's designed to be read by humans instead of computers, you should head to our website or reference the HTML-based endpoints.
Using the API
The next few sections will cover different ways to access the API, how to filter the data, how to use autocomplete endpoints, and how to find more information.
You do not need to complete this tutorial in its entirety to get started. Feel free to stop and experiment with your own ideas as you progress.
Endpoint Overview
When you type a URL into your browser, it usually returns a web page: a document that your browser knows how to display for you to read. APIs use URLs too, but instead of returning formatted web pages, API URLs return data that is structured so computers can easily parse it. API URLs are called endpoints. Just as many pages make up a website, many endpoints make up an API.
The FARA.gov API supports a number of endpoints. For example /api/Registrants/xml/Active is our endpoint for active registrants on file with the FARA Unit in XML format.
GET requests
All of the current FARA.gov endpoints require the GET method for making a request.
Requests for a specific record (with a known numerical identifier) are made via a specific GET request URL format. For example, a request to /api/RegistrantDocs/xml/123 would retrieve the agency's metadata (XML format) and hyperlinks to filing documents (PDF format) for registrant number 123.
Some requests are designed to return data for a specific registrant number and others return all records the match the criteria for a given endpoint.
HTML, CSV, XML and JSON formats
For convenience many of the datasets provided by the APIs are available in multiple formats:
HTML - Hypertext Markup Language
This format allows you to view the result set as a web page (i.e. human-readable) and interact via sorting and pagination. HTML endpoints are traditionally used to validate the expected result set found via the other endpoints.
CSV - Comma Separated Values
A comma-separated values (CSV) file is a delimited text file that uses a comma to separate values. A CSV file stores tabular data (numbers and text) in plain text. Each line of the file is a data record. Each record consists of one or more fields, separated by commas. The use of the comma as a field separator is the source of the name for this file format. This format allows for data to be easily loaded into a variety of applications. However, they are best viewed in applications that allow data to be manipulated in columns, most common of which are spreadsheets or databases (Excel, Access, etc.).
Example output in CSV format:
"Registration Number","Registration Date","Name","Business Name","Address 1","Address 2","City","State","Zip"
"1234","01/03/2019","ABC Group, Inc.","Schuster Ltd","343 Jefferson Drive","Suite 101","Washington","PA","15301"
"5678","02/13/2019","XYZ Company LLC","Business-Focused Stable Securedline","48666 N. Boston St.","","Kings Mountain","NC","28086"
"9101","03/23/2019","Alpha Ridge LLC","Metz Inc","511 6th Ave.","","Moorhead","MN","56560"
XML - Extensible Markup Language
Extensible Markup Language (XML) is a markup language that defines a set of rules for encoding documents in a format that is both human-readable and machine-readable. It has documented open standards on the Web (RFC 4825) and has historically been a popular choice for open data interchange. Another advantage of XML is that most browsers render it in a highly readable and organized way. The tree structure of XML lends itself well to this formatting, and allows for browsers to let users to naturally collapse individual tree elements.
Example output in XML format:
<?xml version="1.0" encoding="utf-8" ?>
<REGISTRANTS_XML_ACTIVE>
<ROW ROWNUM="1">
<Registration_Number>1234</Registration_Number>
<Registration_Date>01/03/2019</Registration_Date>
<Name>ABC Group, Inc.</Name>
<Business_Name>Schuster Ltd</Business_Name>
<Address_1>343 Jefferson Drive</Address_1>
<Address_2>Suite 101</Address_2>
<City>Washington</City>
<State>PA</State>
<Zip>15301</Zip>
</ROW>
<ROW ROWNUM="2">
<Registration_Number>5678</Registration_Number>
<Registration_Date>02/13/2019</Registration_Date>
<Name>XYZ Company LLC</Name>
<Business_Name>Business-Focused Stable Securedline</Business_Name>
<Address_1>48666 N. Boston St.</Address_1>
<Address_2/>
<City>Kings Mountain</City>
<State>NC</State>
<Zip>28086</Zip>
</ROW>
<ROW ROWNUM="3">
<Registration_Number>9101</Registration_Number>
<Registration_Date>03/23/2019</Registration_Date>
<Name>Alpha Ridge LLC</Name>
<Business_Name>Metz Inc</Business_Name>
<Address_1>511 6th Ave.</Address_1>
<Address_2/>
<City>Moorhead</City>
<State>MN</State>
<Zip>56560</Zip>
</ROW>
</REGISTRANTS_XML_ACTIVE>
JSON - JavaScript Object Notation
JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format. JSON uses human-readable text to transmit data objects consisting of attribute–value pairs and array data types (or any other serializable value). It has documented open standards on the Web (RFC 4825) and is a very common data format used for asynchronous browser–server communication. Even though it closely resembles JavaScript object literal syntax, it can be used independently from JavaScript, and many programming environments feature the ability to read (parse) and generate JSON.
Example output in JSON format:
{
"REGISTRANTDOCS":{
"ROW":[
{
"ROWNUM":1,
"Registration_Number":1234,
"Registration_Date":"01/03/2019",
"Name":"ABC Group, Inc.",
"Business_Name":"Schuster Ltd",
"Address_1":"343 Jefferson Drive",
"Address_2":"Suite 101",
"City":"Washington",
"State":"PA",
"Zip":15301
},
{
"ROWNUM":2,
"Registration_Number":5678,
"Registration_Date":"02/13/2019",
"Name":"XYZ Company LLC",
"Business_Name":"Business-Focused Stable Securedline",
"Address_1":"48666 N. Boston St.",
"Address_2":"",
"City":"Kings Mountain",
"State":"NC",
"Zip":28086
},
{
"ROWNUM":3,
"Registration_Number":9101,
"Registration_Date":"03/23/2019",
"Name":"Alpha Ridge LLC",
"Business_Name":"Metz Inc",
"Address_1":"511 6th Ave.",
"Address_2":"",
"City":"Moorhead",
"State":"MN",
"Zip":56560
}
]
}
}
For more details on FARA.gov API requests, please continue to the full API documentation here