Developer Information

FHFA is building out different ways to access our public datasets as part of an open effort to increase accessibility, delivery, and use of our digital products.

We invite comments from the normal data users, analysts, developers, etc. Specifically, we are interested in knowing what kinds of data formats are most useful for direct download and whether certain APIs would improve the user experience.

We encourage the public to utilize the data in new, innovative ways and kindly request a simple attribution, like "Source: FHFA". If you use our data to make a cool infographic, website, or mobile app, please let us know! 

Since we are using the house price index (HPI) dataset as one of the initial test cases, feedback can be sent via the Data and Research Contact page.

CSV-to-API

The CSV-to-API tool from labs.data.gov (hosted at GitHub) allows users to query any CSV on the FHFA website.

The tool allows users to either:

1. convert a CSV to another file format, or

2. perform basic operations on the CSV. 

The two tasks can be combined to be performed as RESTful queries as explained below.

Examples with CSV-to-API

The tool can be applied to any dataset that has capitalized variable names in the first row.  Two types of datasets are the FHLB members and the HPI datasets. Many of the HPI datasets are available in CSV format by adding "_api" to the end of the filename, or by changing the file "HPI_PO_us_and_census.xls" to be "HPI_PO_us_and_census_api.csv". The examples below use both the FHLB and HPI data. All of this is still in development and feedback is appreciated.

1. Convert a CSV into another file format:

The type of output is changed with the "format=" command, which takes the values of html, json (default), and xml.  

JSON: Click here to view JSON​​​ version
XML: Click here to view XML version
HTML: Click here to view HTML version  

Here is an example of how to display the FHLB member names in HTML using the CSV file on our site: 

http://labs.data.gov/csv-to-api/?source=http://www.fhfa.gov/DataTools/Downloads/Documents/FHLBank-Member_Data/fhlb_members.csv&format=html​​   

2. Perform basic operations:

Two basic functions, filter and sort, can be performed on datasets. The two functions can be combined and are applied to variable field names, which must be capitalized. The function can only be applied to a single field once time, though. For example, you can filter for the most recent year and quarter but not for the most recent two years.

Filtering

• ​Filter to display the Purchase-only HPI for only the USA

http://labs.data.gov/csv-to-api/?source=http://www.fhfa.gov/DataTools/Downloads/Documents/HPI/HPI_PO_us_and_census_api.csv&format=html&PLACE_ID=USA

Sorting

• Sort FHLB member names in descending order

http://labs.data.gov/csv-to-api/?source=http://www.fhfa.gov/DataTools/Downloads/Documents/FHLBank-Member_Data/fhlb_members.csv&format=html&sort=member_name&sort_dir=desc

• Sort the Purchase-Only HPI data by the seasonally-adjusted index and filter for 2013Q4

http://labs.data.gov/csv-to-api/?source=http://www.fhfa.gov/DataTools/Downloads/Documents/HPI/HPI_PO_metro_api.csv&format=html&YEAR=2013&PERIOD=4&sort=SA_INDEX 

HTTP Status Code Descriptions

400: Indicates a "Format not supported" (a bad request) where the file format is not supported. An example is specifying a .XLS file.

502: Indicates a "Bad data source" (or bad gateway) where the source filename does not exist. An example is specifying a .CSV that is not hosted on the website.

Other Limitations

The source file is restricted to a CSV. If a download occurs after executing a query (instead of returning results in the browser) then rename the file with the desired extension that you passed through the URL (e.g. "csv-to-api" could be renamed to "csv-to-api.json").

The sort function is restricted currently to a single variable (e.g. sorting can be by yr or period but not both). The CSI-to-API tool has a maximum observation limit in a CSV (a known limit is 90,000 rows but it may be smaller).

Other agency hubs that influenced our development
Census, FCC, HUD, NASA, USA.gov