{
  "openapi": "3.1.0",
  "info": {
    "title": "See You Mortgage data files",
    "version": "1",
    "summary": "Current mortgage rates from 400+ US credit unions as static JSON and CSV files.",
    "description": "Plain files rebuilt whenever a rate changes, usually daily. Fetch /data/manifest.json first: it says when the files were built and what exists. A path that doesn't exist returns HTTP 404 with a small HTML page. Field meanings and caveats: https://see-you-mortgage.web.app/data/"
  },
  "servers": [
    {
      "url": "https://see-you-mortgage.web.app"
    }
  ],
  "paths": {
    "/data/manifest.json": {
      "get": {
        "operationId": "getManifest",
        "summary": "When the files were built, counts, and which files exist",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Manifest"
                }
              }
            }
          }
        }
      }
    },
    "/data/rates.json": {
      "get": {
        "operationId": "getRates",
        "summary": "Every rate quote on the site, with membership, financing states, ARM terms and lender fees joined in",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RatesFile"
                }
              }
            }
          }
        }
      }
    },
    "/data/rates.csv": {
      "get": {
        "operationId": "getRatesCsv",
        "summary": "The same quotes as a flat table: Institution, Domain, Product, Rate %, Points, APR %, Payment per $100K, As Of, Source URL, Financing States (| separated, or ALL for the 50 states and DC), Membership, Product Kind, Term Months, Fixed Months, Loan Type",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/data/by-state/{state}/{product}.json": {
      "get": {
        "operationId": "getRatesByStateAndProduct",
        "summary": "The quotes usable for a property in one state, one product bucket, sorted by APR; small enough to read in one fetch. Lenders recorded as financing there, plus those with no recorded lending area (flagged unknown in the lenders table).",
        "parameters": [
          {
            "name": "state",
            "in": "path",
            "required": true,
            "description": "Two-letter postal code of a US state, or DC",
            "schema": {
              "type": "string",
              "pattern": "^[A-Z]{2}$",
              "example": "PA"
            }
          },
          {
            "name": "product",
            "in": "path",
            "required": true,
            "description": "A term bucket (fixed-30, fixed-20, fixed-15, fixed-10, fixed-other, arm) for conforming and high-balance loans, with -jumbo, -government (FHA, VA, USDA) or -medical (medical professional loans) appended for those loan types, e.g. fixed-30-government; or other. The state's index file lists which exist. A bucket too big for one file continues in {product}-2.json, -3 and so on: follow each file's next.",
            "schema": {
              "type": "string",
              "pattern": "^(fixed-(30|20|15|10|other)|arm)(-jumbo|-government|-medical)?$|^other$",
              "example": "fixed-30"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK. A missing combination returns the homepage HTML; the state's index file says which exist.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StateProductFile"
                }
              }
            }
          },
          "404": {
            "description": "No such state or product. The body is the site's HTML 404 page, not JSON; the manifest lists what exists.",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/data/by-state/{state}.json": {
      "get": {
        "operationId": "getStateIndex",
        "summary": "Which product files a state has and how many rows each holds",
        "parameters": [
          {
            "name": "state",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "PA",
              "pattern": "^[A-Z]{2}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StateIndex"
                }
              }
            }
          },
          "404": {
            "description": "No such state or product. The body is the site's HTML 404 page, not JSON; the manifest lists what exists.",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Manifest": {
        "type": "object",
        "properties": {
          "site": {
            "type": "string"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "institutions": {
            "type": "integer"
          },
          "rows": {
            "type": "integer"
          },
          "files": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Paths of the data files, relative to the site"
          },
          "byState": {
            "type": "object",
            "description": "URL patterns for the by-state files and the state and product values they take"
          }
        }
      },
      "RatesFile": {
        "type": "object",
        "properties": {
          "site": {
            "type": "string"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "institutions": {
            "type": "integer",
            "description": "Distinct credit unions in rates"
          },
          "rates": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RateRecord"
            }
          }
        }
      },
      "RateRecord": {
        "type": "object",
        "properties": {
          "institution": {
            "type": "string"
          },
          "domain": {
            "type": "string",
            "description": "The credit union's website; the stable key for one lender"
          },
          "product": {
            "type": "string",
            "description": "Product name as the credit union publishes it"
          },
          "productType": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/ProductType"
              },
              {
                "type": "null"
              }
            ],
            "description": "null when the product can't finance an ordinary home purchase (home equity lines, refinance-only, land, construction, first-time-buyer programs, interest-only, ...)"
          },
          "rate": {
            "type": [
              "number",
              "null"
            ],
            "description": "Percent, e.g. 6.125"
          },
          "points": {
            "type": [
              "number",
              "null"
            ],
            "description": "Percent of the loan amount paid up front; see asScraped.points when a credit union quotes dollars or n/a"
          },
          "apr": {
            "type": [
              "number",
              "null"
            ],
            "description": "Percent"
          },
          "paymentPer100k": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Monthly principal and interest per $100,000 borrowed, dollars (the credit union's $300,000 figure divided by three)"
          },
          "asScraped": {
            "type": "object",
            "properties": {
              "rate": {
                "type": "string"
              },
              "points": {
                "type": "string"
              },
              "apr": {
                "type": "string"
              },
              "payment": {
                "type": "string"
              }
            },
            "description": "The figures exactly as printed on the credit union's page"
          },
          "asOf": {
            "type": "string",
            "format": "date",
            "description": "Day the credit union's rate page was last read successfully; older than two days may have moved"
          },
          "sourceUrl": {
            "type": "string",
            "description": "The credit union's page the quote came from"
          },
          "financingStates": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "States where the credit union finances property; empty means nationwide or unknown"
          },
          "membership": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "summary": {
                "type": "string",
                "description": "As the rate cards phrase it, e.g. \"Anyone can join\""
              },
              "categories": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "detail": {
                "type": "string"
              },
              "link": {
                "type": "string"
              },
              "affinityOrganization": {
                "type": "string",
                "description": "An organization anyone can join to qualify, with its fee when known"
              },
              "originationFee": {
                "type": "string",
                "description": "A flat lender fee the cards add to the points, when charged"
              },
              "joinCost": {
                "type": [
                  "string",
                  "null"
                ],
                "enum": [
                  "low",
                  "medium",
                  "high",
                  null
                ],
                "description": "For lenders anyone can join, how much it takes someone with no affiliation (low: free to about $10 or the credit union pays the association fee, all online; medium: about $15-50, joining an outside group yourself, or a mailed form; high: more than about $50 up front, or applying in person at a branch. A year of association dues counts once). null when not rated."
              },
              "joinCostDetail": {
                "type": "string",
                "description": "What joining takes, in a sentence; empty when not rated"
              },
              "ongoingDues": {
                "type": [
                  "string",
                  "null"
                ],
                "enum": [
                  "yes",
                  "no",
                  "unknown",
                  null
                ],
                "description": "Whether you must keep paying to stay a member: no where nothing recurs or the credit union says membership lasts, unknown when unstated"
              },
              "eligibilityQuote": {
                "type": [
                  "object",
                  "null"
                ],
                "description": "The credit union's own words on who can join, copied verbatim from its site",
                "properties": {
                  "text": {
                    "type": "string"
                  },
                  "url": {
                    "type": "string",
                    "description": "The page the text was copied from"
                  },
                  "asOf": {
                    "type": "string",
                    "description": "When it was read (YYYY-MM-DD)"
                  }
                }
              }
            }
          },
          "armTerms": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "summary": {
                "type": "string"
              },
              "caps": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "index": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "indexShort": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "currentIndex": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "margin": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "initialFixedMonths": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "adjustmentPeriodMonths": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "lifetimeCap": {
                "type": [
                  "number",
                  "null"
                ]
              }
            }
          },
          "lenderFees": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "amount": {
                "type": "integer",
                "description": "Dollars of lender fees implied by the published APR"
              },
              "onLoanAmount": {
                "type": "integer"
              },
              "points": {
                "type": "string"
              },
              "asOf": {
                "type": "string"
              }
            },
            "description": "An estimate excluding third-party costs; confirm on a Loan Estimate"
          },
          "newMembers": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "open",
                  "established_only"
                ]
              },
              "confirmed": {
                "type": "string"
              },
              "notes": {
                "type": "string"
              }
            },
            "description": "Whether the rate was confirmed available to new members; null where not checked"
          }
        }
      },
      "ProductType": {
        "type": "object",
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "fixed",
              "arm"
            ]
          },
          "termMonths": {
            "type": "integer"
          },
          "fixedMonths": {
            "type": "integer",
            "description": "Months before the first rate adjustment; equals termMonths for fixed loans"
          },
          "adjustMonths": {
            "type": "integer",
            "description": "Months between adjustments; 0 for fixed loans"
          },
          "loanType": {
            "type": "string",
            "enum": [
              "Conforming",
              "High Balance",
              "Jumbo",
              "FHA",
              "VA",
              "USDA",
              "Medical Professional"
            ]
          }
        }
      },
      "StateIndex": {
        "type": "object",
        "properties": {
          "site": {
            "type": "string"
          },
          "state": {
            "type": "string"
          },
          "lenders": {
            "type": "integer"
          },
          "rows": {
            "type": "integer"
          },
          "files": {
            "type": "object",
            "additionalProperties": {
              "type": "object",
              "properties": {
                "path": {
                  "type": "string"
                },
                "rows": {
                  "type": "integer"
                },
                "pages": {
                  "type": "integer",
                  "description": "How many files the bucket spans (follow next)"
                }
              }
            }
          },
          "fields": {
            "type": "string"
          }
        }
      },
      "StateProductFile": {
        "type": "object",
        "properties": {
          "site": {
            "type": "string"
          },
          "state": {
            "type": "string"
          },
          "product": {
            "type": "string"
          },
          "fields": {
            "type": "string",
            "description": "Where the columns are explained"
          },
          "lenders": {
            "type": "object",
            "description": "Keyed by domain (or name when the lender has none); each value is an array in lenderColumns order. states is the financing-state list when few, else how many of the 50 states and DC it covers ('48 of 51', 'all 51'), or 'unknown'; inState is 'listed' when the lender records financing property in this state, 'unknown' when its area isn't recorded; sourceUrl is the lender's rate page and asOf when it was last read (from its cheapest row in this file)",
            "additionalProperties": {
              "type": "array"
            }
          },
          "columns": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "lender (key into lenders), product, kind, termMonths, fixedMonths, adjustMonths, loanType, rate, points, apr, paymentPer100k, asOf, sourceUrl, armTerms, lenderFees"
          },
          "rows": {
            "type": "array",
            "items": {
              "type": "array",
              "description": "One quote, values in column order, sorted by APR ascending; asOf and sourceUrl are null where they equal the lender's"
            }
          },
          "lenderColumns": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "institution, join, joinLink, originationFee, newMembers, openToAnyone, joinCost, joinCostDetail, ongoingDues, eligibilityUnverified (why nobody can confirm who gets the rate, e.g. a relocation program; such rows sort last), states, inState, sourceUrl, asOf. Each lender's full membership record, with eligibilityQuote (its own words on who can join, verbatim), is at /data/lenders/<domain>.json (index: /data/lenders/index.json)."
          },
          "notes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "How to read the file: sort order, what null means in rows, inState, units"
          },
          "page": {
            "type": "integer"
          },
          "pages": {
            "type": "integer"
          },
          "next": {
            "type": [
              "string",
              "null"
            ],
            "description": "Path of the bucket's next page (same layout, APR order continues), or null on the last page"
          }
        }
      }
    }
  }
}
