{
    "openapi": "3.1.0",
    "info": {
        "title": "The Loan Week API",
        "version": "1.0.0",
        "summary": "Loan payments at the latest published average rates, and the averages themselves.",
        "description": "Read-only and free, no key. Monthly payment, total interest and total paid for mortgages, car, personal and student loans, priced at the latest average rate (Freddie Mac PMMS, Federal Reserve G.19, U.S. Department of Education) unless you pass your own rate. Figures are averages and estimates, not loan offers. 60 requests per minute per IP address.",
        "contact": {
            "name": "Pablo Bravo Villanueva",
            "email": "pablobravo44@gmail.com",
            "url": "https://theloanweek.com/contact/"
        },
        "license": {
            "name": "Free with attribution",
            "url": "https://theloanweek.com/terms/"
        }
    },
    "servers": [
        {
            "url": "https://theloanweek.com",
            "description": "Production"
        }
    ],
    "externalDocs": {
        "description": "API documentation",
        "url": "https://theloanweek.com/api/"
    },
    "tags": [
        {
            "name": "payments",
            "description": "Loan payment calculations"
        },
        {
            "name": "rates",
            "description": "Latest published average rates"
        }
    ],
    "paths": {
        "/api/v1/payment": {
            "get": {
                "operationId": "getPayment",
                "tags": [
                    "payments"
                ],
                "summary": "Monthly payment, total interest and total paid for a fixed-rate loan",
                "parameters": [
                    {
                        "name": "type",
                        "in": "query",
                        "required": false,
                        "description": "Loan type; sets the default rate and term and how `term` is read",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "mortgage",
                                "car",
                                "personal",
                                "student"
                            ],
                            "default": "mortgage"
                        }
                    },
                    {
                        "name": "amount",
                        "in": "query",
                        "required": true,
                        "description": "Amount borrowed in US dollars: more than 0, up to 20,000,000 for mortgages and 1,000,000 for the other types. Commas and \"$\" are ignored.",
                        "schema": {
                            "type": "number",
                            "exclusiveMinimum": 0,
                            "maximum": 20000000
                        },
                        "example": 300000
                    },
                    {
                        "name": "rate",
                        "in": "query",
                        "required": false,
                        "description": "Annual interest rate in percent (0 to 40). Omit to use the latest published average for the type (mortgage: Freddie Mac 30-year; car: Fed G.19 new-car rate, 48-month series for terms up to 48 months, else 60-month; personal: Fed G.19 24-month; student: federal undergraduate rate).",
                        "schema": {
                            "type": "number",
                            "minimum": 0,
                            "maximum": 40
                        },
                        "example": 6.5
                    },
                    {
                        "name": "term",
                        "in": "query",
                        "required": false,
                        "description": "Loan length: years for mortgage and student loans (default 30 and 10), months for car and personal loans (default 60 and 36). The result must be 1 to 480 months.",
                        "schema": {
                            "type": "number",
                            "exclusiveMinimum": 0
                        },
                        "example": 30
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The payment",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "type",
                                        "amount",
                                        "rate",
                                        "months",
                                        "payment",
                                        "total_interest",
                                        "total_paid",
                                        "rate_source",
                                        "notice",
                                        "page"
                                    ],
                                    "properties": {
                                        "type": {
                                            "type": "string",
                                            "enum": [
                                                "mortgage",
                                                "car",
                                                "personal",
                                                "student"
                                            ]
                                        },
                                        "amount": {
                                            "type": "number"
                                        },
                                        "rate": {
                                            "type": "number",
                                            "description": "Annual rate used, percent"
                                        },
                                        "months": {
                                            "type": "integer"
                                        },
                                        "payment": {
                                            "type": "number",
                                            "description": "Monthly principal and interest, dollars (cents)"
                                        },
                                        "total_interest": {
                                            "type": "number"
                                        },
                                        "total_paid": {
                                            "type": "number"
                                        },
                                        "rate_source": {
                                            "type": [
                                                "object",
                                                "null"
                                            ],
                                            "description": "Where the average rate comes from; null when you passed `rate`.",
                                            "properties": {
                                                "name": {
                                                    "type": "string",
                                                    "description": "Publisher and series, e.g. \"Freddie Mac Primary Mortgage Market Survey (MORTGAGE30US)\""
                                                },
                                                "as_of": {
                                                    "type": "string",
                                                    "format": "date",
                                                    "description": "Date the average describes"
                                                },
                                                "url": {
                                                    "type": "string",
                                                    "format": "uri"
                                                }
                                            }
                                        },
                                        "notice": {
                                            "type": "string"
                                        },
                                        "page": {
                                            "type": "string",
                                            "format": "uri",
                                            "description": "The The Loan Week page for this amount (the nearest amount the site has a page for, or the index of that loan type)"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid parameter",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string",
                                            "description": "What is wrong"
                                        },
                                        "docs": {
                                            "type": "string",
                                            "format": "uri"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit exceeded (60 requests per minute per IP address)",
                        "headers": {
                            "Retry-After": {
                                "schema": {
                                    "type": "integer"
                                },
                                "description": "Seconds to wait"
                            }
                        },
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/rates": {
            "get": {
                "operationId": "getRates",
                "tags": [
                    "rates"
                ],
                "summary": "Latest published average rates with source, series and date",
                "responses": {
                    "200": {
                        "description": "The averages",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "rates": {
                                            "type": "object",
                                            "properties": {
                                                "m30": {
                                                    "type": "object",
                                                    "properties": {
                                                        "label": {
                                                            "type": "string"
                                                        },
                                                        "value": {
                                                            "type": "number",
                                                            "description": "Average rate, percent"
                                                        },
                                                        "as_of": {
                                                            "type": "string",
                                                            "format": "date"
                                                        },
                                                        "series_id": {
                                                            "type": "string",
                                                            "description": "FRED series id"
                                                        },
                                                        "source": {
                                                            "type": "string"
                                                        },
                                                        "url": {
                                                            "type": "string",
                                                            "format": "uri"
                                                        },
                                                        "frequency": {
                                                            "type": "string",
                                                            "description": "\"weekly\" for Freddie Mac; the Federal Reserve G.19 series are quarterly surveys"
                                                        }
                                                    },
                                                    "description": "30-year fixed mortgage, Freddie Mac PMMS (weekly)"
                                                },
                                                "m15": {
                                                    "type": "object",
                                                    "properties": {
                                                        "label": {
                                                            "type": "string"
                                                        },
                                                        "value": {
                                                            "type": "number",
                                                            "description": "Average rate, percent"
                                                        },
                                                        "as_of": {
                                                            "type": "string",
                                                            "format": "date"
                                                        },
                                                        "series_id": {
                                                            "type": "string",
                                                            "description": "FRED series id"
                                                        },
                                                        "source": {
                                                            "type": "string"
                                                        },
                                                        "url": {
                                                            "type": "string",
                                                            "format": "uri"
                                                        },
                                                        "frequency": {
                                                            "type": "string",
                                                            "description": "\"weekly\" for Freddie Mac; the Federal Reserve G.19 series are quarterly surveys"
                                                        }
                                                    },
                                                    "description": "15-year fixed mortgage, Freddie Mac PMMS (weekly)"
                                                },
                                                "auto60": {
                                                    "type": "object",
                                                    "properties": {
                                                        "label": {
                                                            "type": "string"
                                                        },
                                                        "value": {
                                                            "type": "number",
                                                            "description": "Average rate, percent"
                                                        },
                                                        "as_of": {
                                                            "type": "string",
                                                            "format": "date"
                                                        },
                                                        "series_id": {
                                                            "type": "string",
                                                            "description": "FRED series id"
                                                        },
                                                        "source": {
                                                            "type": "string"
                                                        },
                                                        "url": {
                                                            "type": "string",
                                                            "format": "uri"
                                                        },
                                                        "frequency": {
                                                            "type": "string",
                                                            "description": "\"weekly\" for Freddie Mac; the Federal Reserve G.19 series are quarterly surveys"
                                                        }
                                                    },
                                                    "description": "60-month new-car loan at commercial banks, Federal Reserve G.19"
                                                },
                                                "auto48": {
                                                    "type": "object",
                                                    "properties": {
                                                        "label": {
                                                            "type": "string"
                                                        },
                                                        "value": {
                                                            "type": "number",
                                                            "description": "Average rate, percent"
                                                        },
                                                        "as_of": {
                                                            "type": "string",
                                                            "format": "date"
                                                        },
                                                        "series_id": {
                                                            "type": "string",
                                                            "description": "FRED series id"
                                                        },
                                                        "source": {
                                                            "type": "string"
                                                        },
                                                        "url": {
                                                            "type": "string",
                                                            "format": "uri"
                                                        },
                                                        "frequency": {
                                                            "type": "string",
                                                            "description": "\"weekly\" for Freddie Mac; the Federal Reserve G.19 series are quarterly surveys"
                                                        }
                                                    },
                                                    "description": "48-month new-car loan at commercial banks, Federal Reserve G.19"
                                                },
                                                "pers24": {
                                                    "type": "object",
                                                    "properties": {
                                                        "label": {
                                                            "type": "string"
                                                        },
                                                        "value": {
                                                            "type": "number",
                                                            "description": "Average rate, percent"
                                                        },
                                                        "as_of": {
                                                            "type": "string",
                                                            "format": "date"
                                                        },
                                                        "series_id": {
                                                            "type": "string",
                                                            "description": "FRED series id"
                                                        },
                                                        "source": {
                                                            "type": "string"
                                                        },
                                                        "url": {
                                                            "type": "string",
                                                            "format": "uri"
                                                        },
                                                        "frequency": {
                                                            "type": "string",
                                                            "description": "\"weekly\" for Freddie Mac; the Federal Reserve G.19 series are quarterly surveys"
                                                        }
                                                    },
                                                    "description": "24-month personal loan at commercial banks, Federal Reserve G.19"
                                                },
                                                "student": {
                                                    "type": "object",
                                                    "description": "Federal Direct Loan fixed rates for the current school year",
                                                    "properties": {
                                                        "label": {
                                                            "type": "string"
                                                        },
                                                        "undergrad": {
                                                            "type": "number"
                                                        },
                                                        "grad_unsub": {
                                                            "type": "number"
                                                        },
                                                        "plus": {
                                                            "type": "number"
                                                        },
                                                        "as_of": {
                                                            "type": "string",
                                                            "format": "date"
                                                        },
                                                        "source": {
                                                            "type": "string"
                                                        },
                                                        "url": {
                                                            "type": "string",
                                                            "format": "uri"
                                                        }
                                                    }
                                                }
                                            }
                                        },
                                        "notice": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit exceeded (60 requests per minute per IP address)",
                        "headers": {
                            "Retry-After": {
                                "schema": {
                                    "type": "integer"
                                },
                                "description": "Seconds to wait"
                            }
                        },
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}