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 Name	Options
years	2018, 2019, 2020, 2021, 2022

LEI Filter

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

Variable Name	Options
leis	List of Legal Entity Identifiers

Geographic Filters

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

Geography	Format
msamds	Five Digit MSA/MD Code
states	Two Letter State Abbreviation (Eg. AL for Alabama)
counties	Five 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 Name	Options
construction_methods	1,2
dwelling_categories	Single Family (1-4 Units):Site-Built Multifamily:Site-Built Single Family (1-4 Units):Manufactured Multifamily:Manufactured
ethnicities	Hispanic or Latino Not Hispanic or Latino Joint Ethnicity Not Available Free Form Text Only
lien_statuses	1,2
loan_products	Conventional: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_purposes	1,2,31,32,4,5
loan_types	1,2,3,4
races	Asian 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
sexes	Male Female Joint Sex Not Available
total_units	1,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

var	value
years	2018
states	MD
actions_taken	5,6
races	Asian

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 Name	Options
years	CSV list of years (example: 2018,2019)
states	two letter state code
msamds	5 digit integer code
counties	5 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"
  }