Skip to main content

Data Browser API

The data browser api enables users to interact with subsets of the HMDA data. Given a list of filters on the data that are entered as parameters in the endpoint the APIs will return either an aggregated report of the data in JSON format or a CSV of the raw data.

This API is what powers the HMDA Data Browser application

Note: depending on the query, queries may take a while to return and data may be too large for conventional spread sheet applications.

HMDA Data Endpoints

Nationwide Aggregation Report

GET https://ffiec.cfpb.gov/v2/data-browser-api/view/nationwide/aggregations

This endpoint is used to generated JSON reports on the entirety of the US. The year parameter and at least one HMDA data parameter are required when calling this endpoint.

Aggregation Report

GET https://ffiec.cfpb.gov/v2/data-browser-api/view/aggregations

This endpoint is used to generated JSON reports on an LEI and/or geography subset. The year parameter and at least one HMDA data parameter are required when calling this endpoint. Additionally, either one geographic parameter or the LEI parameter are required when calling this endpoint. Both a geographic parameter and LEI may be provided.

Nationwide Data Subset as CSV

GET https://ffiec.cfpb.gov/v2/data-browser-api/view/nationwide/csv

This endpoint is used to download raw HMDA on the entirety of the US, data given the applied filters in csv format. The file will be streamed. The year parameter and at least one HMDA data parameter are required when calling this endpoint.

Data Subset as CSV

GET https://ffiec.cfpb.gov/v2/data-browser-api/view/csv

This endpoint is used to download raw HMDA data given the applied filters in csv format. The file will be streamed. The year parameter and at least one HMDA data parameter are required when calling this endpoint. Additionally, either one geographic parameter or the LEI parameter are required when calling this endpoint. Both a geographic parameter and LEI may be provided.

Filters

Year Filter

All requests must include a year that defines the filing period of the data.

Variable NameOptions
years2018, 2019, 2020, 2021, 2022

LEI Filter

The LEI Filter allows users to filter by specific financial institutions.

Variable NameOptions
leisList of Legal Entity Identifiers

Geographic Filters

The HMDA Data Browser requires exactly one geographic filter for all non-nationwide requests.

GeographyFormat
msamdsFive Digit MSA/MD Code
statesTwo Letter State Abbreviation (Eg. AL for Alabama)
countiesFive Digit County FIPS Code

HMDA Data Filters

HMDA Data requests support the following filters. At least one HMDA date filter is required, multiple options are acceptable.

Variable NameOptions
construction_methods1,2
dwelling_categoriesSingle Family (1-4 Units):Site-Built
Multifamily:Site-Built
Single Family (1-4 Units):Manufactured
Multifamily:Manufactured
ethnicitiesHispanic or Latino
Not Hispanic or Latino
Joint
Ethnicity Not Available
Free Form Text Only
lien_statuses1,2
loan_productsConventional:First Lien
FHA:First Lien
VA:First Lien
FSA/RHS:First Lien
Conventional:Subordinate Lien
FHA:Subordinate Lien
VA:Subordinate Lien
FSA/RHS:Subordinate Lien
loan_purposes1,2,31,32,4,5
loan_types1,2,3,4
racesAsian
Native Hawaiian or Other Pacific Islander
Free Form Text Only
Race Not Available
American Indian or Alaska Native
Black or African American
2 or more minority races
White
Joint
sexesMale
Female
Joint
Sex Not Available
total_units1,2,3,4,5-24,25-49,50-99,100-149,>149

Dataset Aggregation

Method: GET
Endpoint: https://ffiec.cfpb.gov/v2/data-browser-api/view/aggregations?years={{}}

Example

Request:

curl "https://ffiec.cfpb.gov/v2/data-browser-api/view/aggregations?states=MD&years=2018&actions_taken=5,6&races=White,Asian,Joint"

GET JSON with the following parameters

varvalue
years2018
statesMD
actions_taken5,6
racesAsian

JSON Response:

  {
"parameters": {
"state": "MD",
"actions_taken": "5,6",
"races": "Asian"
},
"aggregations": [
{
"count": 679,
"sum": 1.90835E8,
"actions_taken": "5",
"races": "Asian",
"state": "MD"
},
{
"count": 716,
"sum": 2.5435E8,
"actions_taken": "6",
"races": "Asian",
"state": "MD"
}
],
"servedFrom": "cache"
}

Dataset CSV Download

Method: GET
Endpoint: https://ffiec.cfpb.gov/v2/data-browser-api/view/csv?years={{}}

Example

Request:

  curl -L "https://ffiec.cfpb.gov/v2/data-browser-api/view/csv?states=CA,MD,DC&years=2018&actions_taken=5"

CSV Response:

HMDA Filers

GET https://ffiec.cfpb.gov/v2/data-browser-api/view/filers

This endpoint can be used to fetch list of financial institutions present in the HMDA dataset. The year parameter is required when calling this endpoint.

HMDA Filer Parameters

Parameter NameOptions
yearsCSV list of years (example: 2018,2019)
statestwo letter state code
msamds5 digit integer code
counties5 digit integer code

Example

Request:

  curl "https://ffiec.cfpb.gov/v2/data-browser-api/view/filers?states=MD,DC&years=2018"

JSON Format Response:

  {
"institutions":[
{
"lei":"lei",
"name":"institution name",
"period":2018
},
{
"lei":"lei",
"name":"institution name",
"period":2018
}
]
}

Errors

Incorrect calls will result in an error. For example the following call will result in an error since there is no state(s)/msamds and years provided.

Request:

curl "https://ffiec.cfpb.gov/v2/data-browser-api/view/csv"

JSON Response:

  {
"errorType": "provide-atleast-msamds-or-states",
"message": "Provide year and either states or msamds or both"
}

ffiec.cfpb.gov

An official website of the CFPB's HMDA  v3.0.9

Looking for U.S. government information and services?  
Visit USA.gov