{"openapi":"3.1.0","info":{"version":"1.0.0","title":"Rates API","description":"Rates API gives the interest rates of New Zealand financial institutions for mortgages, personal loans, car loans, and credit cards.\n\n- The API collects data from [interest.co.nz](https://www.interest.co.nz) each hour.\n- The API keeps one snapshot of each dataset for each day on which the data changes. Use the time-series endpoints to get these snapshots.\n- You do not need an API key.\n- All responses are JSON.\n- AI agents can get the same data through the MCP endpoint.\n\nThe data can be incorrect. For correct rates, refer to the financial institution.","contact":{"name":"Rates API on GitHub","url":"https://github.com/simonbetton/ratesapi.nz/issues"}},"externalDocs":{"description":"Guides, concepts, and AI integration","url":"https://www.ratesapi.nz/docs/api-reference"},"tags":[{"name":"Mortgage Rates","description":"Interest rates for mortgages (home loans). Each rate has a fixed term from 6 months to 5 years, or it is a variable floating rate."},{"name":"Personal Loan Rates","description":"Interest rates for personal loans. A rate can have a plan, for example, `Secured`, and a condition, for example, a loan amount."},{"name":"Car Loan Rates","description":"Interest rates for car loans. A rate can have a plan, for example, `Secured`, and a condition, for example, a loan amount."},{"name":"Credit Card Rates","description":"Credit card issuers and their plans, with interest rates and card fees."},{"name":"Health","description":"The status of the API, and the time of the last change and the last data collection for each dataset."},{"name":"MCP","description":"The Model Context Protocol (MCP) endpoint. AI agents and MCP clients use it to find and call tools that get Rates API data."}],"security":[],"servers":[{"url":"https://www.ratesapi.nz","description":"Production"}],"paths":{"/api/v1/mortgage-rates":{"get":{"operationId":"listMortgageRates","tags":["Mortgage Rates"],"summary":"Get mortgage rates for all institutions","description":"This endpoint gets the newest mortgage rates for all institutions. Each institution contains products, and each product contains rates.\n\nTo get only the rates for one fixed term, send `termInMonths`.\n\nUse this endpoint to compare mortgage rates between institutions.","parameters":[{"name":"termInMonths","in":"query","required":false,"schema":{"pattern":"^\\d+$","examples":["12"],"type":"string"},"description":"The fixed mortgage term in months. Use digits only. For example, `12` is a fixed term of 1 year. The data contains terms of 6, 12, 18, 24, 36, 48, and 60 months. When you use this parameter, the response does not contain variable floating rates."}],"responses":{"200":{"description":"The newest mortgage rates.","content":{"application/json":{"schema":{"additionalProperties":false,"description":"The newest mortgage rates.","type":"object","required":["type","data","lastUpdated","termsOfUse","timestamp"],"properties":{"type":{"description":"The type of data. The value is always `MortgageRates`.","const":"MortgageRates","type":"string"},"data":{"title":"MortgageRates","description":"The institutions and their mortgage rates.","type":"array","items":{"additionalProperties":false,"type":"object","required":["id","name","products"],"properties":{"id":{"pattern":"^institution:","description":"The ID of the institution. Use this value for the `institutionId` parameter.","examples":["institution:anz"],"type":"string"},"name":{"description":"The name of the institution.","examples":["ANZ","Kiwibank","Westpac"],"type":"string"},"products":{"description":"The mortgage products of this institution.","type":"array","items":{"additionalProperties":false,"type":"object","required":["id","name","rates"],"properties":{"id":{"pattern":"^product:","description":"The ID of the mortgage product.","examples":["product:anz:standard"],"type":"string"},"name":{"description":"The name of the product that the institution uses.","examples":["Standard"],"type":"string"},"rates":{"description":"The rates for this product. Each rate has a different term.","type":"array","items":{"additionalProperties":false,"type":"object","required":["id","rate","term","termInMonths"],"properties":{"id":{"pattern":"^rate:","description":"The ID of the rate.","examples":["rate:anz:standard:18-months"],"type":"string"},"rate":{"description":"The interest rate for each year, in %. For example, `4.29` is 4.29 %.","examples":[4.29],"type":"number"},"term":{"default":"Variable floating","description":"The term of the rate. `Variable floating` is a rate that the institution can change at any time. All other values are fixed terms.","examples":["6 months","3 years"],"type":"string","enum":["Variable floating","6 months","18 months","1 year","2 years","3 years","4 years","5 years"]},"termInMonths":{"description":"The fixed term in months. The value is `null` for a variable floating rate.","examples":[6,36],"type":["number","null"]}}}}}}}}}},"lastUpdated":{"description":"The date and time (UTC, ISO 8601) when the API collected this data from the source.","examples":["2021-08-01T00:00:00.000Z"],"type":"string"},"termsOfUse":{"description":"The terms of use for the data. The data can be incorrect. For correct rates, refer to the financial institution.","type":"string"},"timestamp":{"description":"The date and time (UTC, ISO 8601) when the server made this response.","examples":["2025-03-04T02:30:00.000Z"],"type":"string"}}}}}},"400":{"description":"The request is not correct. For example, a parameter has an incorrect format, or the endpoint does not use a parameter in the request.","content":{"application/json":{"schema":{"additionalProperties":false,"description":"The request is not correct. For example, a parameter has an incorrect format, or the endpoint does not use a parameter in the request.","type":"object","required":["code","message"],"properties":{"code":{"description":"The HTTP status code of the response.","const":400,"type":"number"},"message":{"description":"A message that tells you about the error.","examples":["Invalid request parameters"],"type":"string"}}}}}},"500":{"description":"An error occurred on the server. Send the request again. If the error continues, refer to the `/api/v1/health` endpoint.","content":{"application/json":{"schema":{"additionalProperties":false,"description":"An error occurred on the server. Send the request again. If the error continues, refer to the `/api/v1/health` endpoint.","type":"object","required":["code","message"],"properties":{"code":{"description":"The HTTP status code of the response.","const":500,"type":"number"},"message":{"description":"A message that tells you about the error.","examples":["An error occurred while retrieving mortgage rates data"],"type":"string"}}}}}}}}},"/api/v1/mortgage-rates/time-series":{"get":{"operationId":"getMortgageRatesTimeSeries","tags":["Mortgage Rates"],"summary":"Get historical mortgage rates","description":"This endpoint gets historical snapshots of mortgage rates. The API keeps one snapshot for each day (UTC) on which the data changed. Some dates do not have a snapshot.\n\nUse one of these options:\n\n- To get one snapshot, send `date`.\n- To get all snapshots in a range, send `startDate` and `endDate`. The range contains the two dates.\n- To get the list of dates that have a snapshot, send no dates. The `availableDates` field contains the list.\n\nDo not send `date` together with `startDate` or `endDate`.\n\nTo get only the data for one institution, send `institutionId`. To get only the rates for one fixed term, send `termInMonths`.","parameters":[{"name":"date","in":"query","required":false,"schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","examples":["2025-03-01"],"type":"string"},"description":"The date of one snapshot, in YYYY-MM-DD format (UTC). Do not use this parameter with `startDate` or `endDate`."},{"name":"startDate","in":"query","required":false,"schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","examples":["2025-01-01"],"type":"string"},"description":"The first date of the range, in YYYY-MM-DD format (UTC). You must also send `endDate`."},{"name":"endDate","in":"query","required":false,"schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","examples":["2025-03-01"],"type":"string"},"description":"The last date of the range, in YYYY-MM-DD format (UTC). You must also send `startDate`. This date must be on or after `startDate`."},{"name":"institutionId","in":"query","required":false,"schema":{"examples":["institution:anz"],"type":"string"},"description":"The ID of an institution. When you use this parameter, the response contains only the data for this institution. You can use upper-case or lower-case letters."},{"name":"termInMonths","in":"query","required":false,"schema":{"pattern":"^\\d+$","examples":["12"],"type":"string"},"description":"The fixed mortgage term in months. Use digits only. For example, `12` is a fixed term of 1 year. The data contains terms of 6, 12, 18, 24, 36, 48, and 60 months. When you use this parameter, the response does not contain variable floating rates."}],"responses":{"200":{"description":"The snapshots for the dates in the request. If the request has no dates, `timeSeries` is empty and `availableDates` shows the dates that you can request.","content":{"application/json":{"schema":{"additionalProperties":false,"description":"The snapshots for the dates in the request. If the request has no dates, `timeSeries` is empty and `availableDates` shows the dates that you can request.","type":"object","required":["type","timeSeries","availableDates","termsOfUse","timestamp"],"properties":{"type":{"description":"The type of data. The value is always `MortgageRatesTimeSeries`.","const":"MortgageRatesTimeSeries","type":"string"},"timeSeries":{"description":"The snapshots. Each key is a snapshot date in YYYY-MM-DD format. Each value contains the data for that date.","type":"object","patternProperties":{"^(.*)$":{"additionalProperties":false,"type":"object","required":["type","data","lastUpdated"],"properties":{"type":{"description":"The type of data. The value is always `MortgageRates`.","const":"MortgageRates","type":"string"},"data":{"title":"MortgageRates","description":"The institutions and their mortgage rates.","type":"array","items":{"additionalProperties":false,"type":"object","required":["id","name","products"],"properties":{"id":{"pattern":"^institution:","description":"The ID of the institution. Use this value for the `institutionId` parameter.","examples":["institution:anz"],"type":"string"},"name":{"description":"The name of the institution.","examples":["ANZ","Kiwibank","Westpac"],"type":"string"},"products":{"description":"The mortgage products of this institution.","type":"array","items":{"additionalProperties":false,"type":"object","required":["id","name","rates"],"properties":{"id":{"pattern":"^product:","description":"The ID of the mortgage product.","examples":["product:anz:standard"],"type":"string"},"name":{"description":"The name of the product that the institution uses.","examples":["Standard"],"type":"string"},"rates":{"description":"The rates for this product. Each rate has a different term.","type":"array","items":{"additionalProperties":false,"type":"object","required":["id","rate","term","termInMonths"],"properties":{"id":{"pattern":"^rate:","description":"The ID of the rate.","examples":["rate:anz:standard:18-months"],"type":"string"},"rate":{"description":"The interest rate for each year, in %. For example, `4.29` is 4.29 %.","examples":[4.29],"type":"number"},"term":{"default":"Variable floating","description":"The term of the rate. `Variable floating` is a rate that the institution can change at any time. All other values are fixed terms.","examples":["6 months","3 years"],"type":"string","enum":["Variable floating","6 months","18 months","1 year","2 years","3 years","4 years","5 years"]},"termInMonths":{"description":"The fixed term in months. The value is `null` for a variable floating rate.","examples":[6,36],"type":["number","null"]}}}}}}}}}},"lastUpdated":{"description":"The date and time (UTC, ISO 8601) when the API collected this data from the source.","examples":["2021-08-01T00:00:00.000Z"],"type":"string"}}}}},"availableDates":{"description":"All dates that have a snapshot, in YYYY-MM-DD format. The list starts with the oldest date.","type":"array","items":{"examples":["2025-03-01"],"type":"string"}},"termsOfUse":{"description":"The terms of use for the data. The data can be incorrect. For correct rates, refer to the financial institution.","type":"string"},"timestamp":{"description":"The date and time (UTC, ISO 8601) when the server made this response.","examples":["2025-03-04T02:30:00.000Z"],"type":"string"},"message":{"description":"A message that tells you how to use this endpoint. The response contains this field only when the request has no dates.","examples":["Please specify a date or date range to retrieve time series data"],"type":"string"}}}}}},"400":{"description":"The request is not correct. For example, a date is not in YYYY-MM-DD format, or `startDate` is after `endDate`. Refer to the endpoint description for the date rules.","content":{"application/json":{"schema":{"additionalProperties":false,"description":"The request is not correct. For example, a date is not in YYYY-MM-DD format, or `startDate` is after `endDate`. Refer to the endpoint description for the date rules.","type":"object","required":["code","message"],"properties":{"code":{"description":"The HTTP status code of the response.","const":400,"type":"number"},"message":{"description":"A message that tells you about the error.","examples":["Invalid request parameters","Start date cannot be after end date"],"type":"string"}}}}}},"404":{"description":"The API did not find data for the parameters in the request. For example, there is no snapshot for the date. Use `availableDates` to find the dates that have a snapshot.","content":{"application/json":{"schema":{"additionalProperties":false,"description":"The API did not find data for the parameters in the request. For example, there is no snapshot for the date. Use `availableDates` to find the dates that have a snapshot.","type":"object","required":["code","message"],"properties":{"code":{"description":"The HTTP status code of the response.","const":404,"type":"number"},"message":{"description":"A message that tells you about the error.","examples":["No data available for date: 2025-03-01","Institution not found for date: 2025-03-01"],"type":"string"}}}}}},"500":{"description":"An error occurred on the server. Send the request again. If the error continues, refer to the `/api/v1/health` endpoint.","content":{"application/json":{"schema":{"additionalProperties":false,"description":"An error occurred on the server. Send the request again. If the error continues, refer to the `/api/v1/health` endpoint.","type":"object","required":["code","message"],"properties":{"code":{"description":"The HTTP status code of the response.","const":500,"type":"number"},"message":{"description":"A message that tells you about the error.","examples":["An error occurred while retrieving mortgage rates data"],"type":"string"}}}}}}}}},"/api/v1/mortgage-rates/{institutionId}":{"get":{"operationId":"getMortgageRatesByInstitution","tags":["Mortgage Rates"],"summary":"Get mortgage rates for one institution","description":"This endpoint gets the newest mortgage rates for one institution. The response has the same structure as the list endpoint, but `data` contains only one institution.\n\nTo get only the rates for one fixed term, send `termInMonths`.","parameters":[{"name":"institutionId","in":"path","required":true,"schema":{"examples":["institution:anz","institution:asb","institution:bnz","institution:kiwibank","institution:westpac"],"type":"string"},"description":"The ID of the institution. Use the `id` of an institution from the list endpoint. You can use upper-case or lower-case letters."},{"name":"termInMonths","in":"query","required":false,"schema":{"pattern":"^\\d+$","examples":["12"],"type":"string"},"description":"The fixed mortgage term in months. Use digits only. For example, `12` is a fixed term of 1 year. The data contains terms of 6, 12, 18, 24, 36, 48, and 60 months. When you use this parameter, the response does not contain variable floating rates."}],"responses":{"200":{"description":"The newest mortgage rates.","content":{"application/json":{"schema":{"additionalProperties":false,"description":"The newest mortgage rates.","type":"object","required":["type","data","lastUpdated","termsOfUse","timestamp"],"properties":{"type":{"description":"The type of data. The value is always `MortgageRates`.","const":"MortgageRates","type":"string"},"data":{"title":"MortgageRates","description":"The institutions and their mortgage rates.","type":"array","items":{"additionalProperties":false,"type":"object","required":["id","name","products"],"properties":{"id":{"pattern":"^institution:","description":"The ID of the institution. Use this value for the `institutionId` parameter.","examples":["institution:anz"],"type":"string"},"name":{"description":"The name of the institution.","examples":["ANZ","Kiwibank","Westpac"],"type":"string"},"products":{"description":"The mortgage products of this institution.","type":"array","items":{"additionalProperties":false,"type":"object","required":["id","name","rates"],"properties":{"id":{"pattern":"^product:","description":"The ID of the mortgage product.","examples":["product:anz:standard"],"type":"string"},"name":{"description":"The name of the product that the institution uses.","examples":["Standard"],"type":"string"},"rates":{"description":"The rates for this product. Each rate has a different term.","type":"array","items":{"additionalProperties":false,"type":"object","required":["id","rate","term","termInMonths"],"properties":{"id":{"pattern":"^rate:","description":"The ID of the rate.","examples":["rate:anz:standard:18-months"],"type":"string"},"rate":{"description":"The interest rate for each year, in %. For example, `4.29` is 4.29 %.","examples":[4.29],"type":"number"},"term":{"default":"Variable floating","description":"The term of the rate. `Variable floating` is a rate that the institution can change at any time. All other values are fixed terms.","examples":["6 months","3 years"],"type":"string","enum":["Variable floating","6 months","18 months","1 year","2 years","3 years","4 years","5 years"]},"termInMonths":{"description":"The fixed term in months. The value is `null` for a variable floating rate.","examples":[6,36],"type":["number","null"]}}}}}}}}}},"lastUpdated":{"description":"The date and time (UTC, ISO 8601) when the API collected this data from the source.","examples":["2021-08-01T00:00:00.000Z"],"type":"string"},"termsOfUse":{"description":"The terms of use for the data. The data can be incorrect. For correct rates, refer to the financial institution.","type":"string"},"timestamp":{"description":"The date and time (UTC, ISO 8601) when the server made this response.","examples":["2025-03-04T02:30:00.000Z"],"type":"string"}}}}}},"400":{"description":"The request is not correct. For example, a parameter has an incorrect format, or the endpoint does not use a parameter in the request.","content":{"application/json":{"schema":{"additionalProperties":false,"description":"The request is not correct. For example, a parameter has an incorrect format, or the endpoint does not use a parameter in the request.","type":"object","required":["code","message"],"properties":{"code":{"description":"The HTTP status code of the response.","const":400,"type":"number"},"message":{"description":"A message that tells you about the error.","examples":["Invalid request parameters"],"type":"string"}}}}}},"404":{"description":"The API did not find an institution with this ID.","content":{"application/json":{"schema":{"additionalProperties":false,"description":"The API did not find an institution with this ID.","type":"object","required":["code","message"],"properties":{"code":{"description":"The HTTP status code of the response.","const":404,"type":"number"},"message":{"description":"A message that tells you about the error.","examples":["Institution not found"],"type":"string"}}}}}},"500":{"description":"An error occurred on the server. Send the request again. If the error continues, refer to the `/api/v1/health` endpoint.","content":{"application/json":{"schema":{"additionalProperties":false,"description":"An error occurred on the server. Send the request again. If the error continues, refer to the `/api/v1/health` endpoint.","type":"object","required":["code","message"],"properties":{"code":{"description":"The HTTP status code of the response.","const":500,"type":"number"},"message":{"description":"A message that tells you about the error.","examples":["An error occurred while retrieving mortgage rates data"],"type":"string"}}}}}}}}},"/api/v1/personal-loan-rates":{"get":{"operationId":"listPersonalLoanRates","tags":["Personal Loan Rates"],"summary":"Get personal loan rates for all institutions","description":"This endpoint gets the newest personal loan rates for all institutions. Each institution contains products, and each product contains rates.\n\nA rate can have a plan, for example, `Secured`, and a condition, for example, a loan amount.\n\nUse this endpoint to compare personal loan rates between institutions.","responses":{"200":{"description":"The newest personal loan rates.","content":{"application/json":{"schema":{"additionalProperties":false,"description":"The newest personal loan rates.","type":"object","required":["type","data","lastUpdated","termsOfUse","timestamp"],"properties":{"type":{"description":"The type of data. The value is always `PersonalLoanRates`.","const":"PersonalLoanRates","type":"string"},"data":{"title":"PersonalLoanRates","description":"The institutions and their personal loan rates.","type":"array","items":{"additionalProperties":false,"type":"object","required":["id","name","products"],"properties":{"id":{"pattern":"^institution:","description":"The ID of the institution. Use this value for the `institutionId` parameter.","examples":["institution:asb"],"type":"string"},"name":{"description":"The name of the institution.","examples":["ANZ","Kiwibank","Westpac"],"type":"string"},"products":{"description":"The personal loan products of this institution.","type":"array","items":{"additionalProperties":false,"type":"object","required":["id","name","rates"],"properties":{"id":{"pattern":"^product:","description":"The ID of the personal loan product.","examples":["product:asb:personal-loan"],"type":"string"},"name":{"description":"The name of the product that the institution uses.","examples":["Personal Loan"],"type":"string"},"rates":{"description":"The rates for this product.","type":"array","items":{"additionalProperties":false,"type":"object","required":["id","rate","plan","condition"],"properties":{"id":{"pattern":"^rate:","description":"The ID of the rate.","examples":["rate:anz:standard:18-months"],"type":"string"},"rate":{"description":"The interest rate for each year, in %. For example, `4.29` is 4.29 %.","examples":[4.29],"type":"number"},"plan":{"description":"The type of loan, for example, `Secured` or `Unsecured`. The value is `null` if the source does not give a type.","examples":["Secured"],"type":["string","null"]},"condition":{"description":"A condition for the rate, for example, a loan amount or a loan term. The value is `null` if the rate has no condition.","examples":["$3,000 to $50,000"],"type":["string","null"]}}}}}}}}}},"lastUpdated":{"description":"The date and time (UTC, ISO 8601) when the API collected this data from the source.","examples":["2021-08-01T00:00:00.000Z"],"type":"string"},"termsOfUse":{"description":"The terms of use for the data. The data can be incorrect. For correct rates, refer to the financial institution.","type":"string"},"timestamp":{"description":"The date and time (UTC, ISO 8601) when the server made this response.","examples":["2025-03-04T02:30:00.000Z"],"type":"string"}}}}}},"500":{"description":"An error occurred on the server. Send the request again. If the error continues, refer to the `/api/v1/health` endpoint.","content":{"application/json":{"schema":{"additionalProperties":false,"description":"An error occurred on the server. Send the request again. If the error continues, refer to the `/api/v1/health` endpoint.","type":"object","required":["code","message"],"properties":{"code":{"description":"The HTTP status code of the response.","const":500,"type":"number"},"message":{"description":"A message that tells you about the error.","examples":["An error occurred while retrieving mortgage rates data"],"type":"string"}}}}}}}}},"/api/v1/personal-loan-rates/time-series":{"get":{"operationId":"getPersonalLoanRatesTimeSeries","tags":["Personal Loan Rates"],"summary":"Get historical personal loan rates","description":"This endpoint gets historical snapshots of personal loan rates. The API keeps one snapshot for each day (UTC) on which the data changed. Some dates do not have a snapshot.\n\nUse one of these options:\n\n- To get one snapshot, send `date`.\n- To get all snapshots in a range, send `startDate` and `endDate`. The range contains the two dates.\n- To get the list of dates that have a snapshot, send no dates. The `availableDates` field contains the list.\n\nDo not send `date` together with `startDate` or `endDate`.\n\nTo get only the data for one institution, send `institutionId`.","parameters":[{"name":"date","in":"query","required":false,"schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","examples":["2025-03-01"],"type":"string"},"description":"The date of one snapshot, in YYYY-MM-DD format (UTC). Do not use this parameter with `startDate` or `endDate`."},{"name":"startDate","in":"query","required":false,"schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","examples":["2025-01-01"],"type":"string"},"description":"The first date of the range, in YYYY-MM-DD format (UTC). You must also send `endDate`."},{"name":"endDate","in":"query","required":false,"schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","examples":["2025-03-01"],"type":"string"},"description":"The last date of the range, in YYYY-MM-DD format (UTC). You must also send `startDate`. This date must be on or after `startDate`."},{"name":"institutionId","in":"query","required":false,"schema":{"examples":["institution:anz"],"type":"string"},"description":"The ID of an institution. When you use this parameter, the response contains only the data for this institution. You can use upper-case or lower-case letters."}],"responses":{"200":{"description":"The snapshots for the dates in the request. If the request has no dates, `timeSeries` is empty and `availableDates` shows the dates that you can request.","content":{"application/json":{"schema":{"additionalProperties":false,"description":"The snapshots for the dates in the request. If the request has no dates, `timeSeries` is empty and `availableDates` shows the dates that you can request.","type":"object","required":["type","timeSeries","availableDates","termsOfUse","timestamp"],"properties":{"type":{"description":"The type of data. The value is always `PersonalLoanRatesTimeSeries`.","const":"PersonalLoanRatesTimeSeries","type":"string"},"timeSeries":{"description":"The snapshots. Each key is a snapshot date in YYYY-MM-DD format. Each value contains the data for that date.","type":"object","patternProperties":{"^(.*)$":{"additionalProperties":false,"type":"object","required":["type","data","lastUpdated"],"properties":{"type":{"description":"The type of data. The value is always `PersonalLoanRates`.","const":"PersonalLoanRates","type":"string"},"data":{"title":"PersonalLoanRates","description":"The institutions and their personal loan rates.","type":"array","items":{"additionalProperties":false,"type":"object","required":["id","name","products"],"properties":{"id":{"pattern":"^institution:","description":"The ID of the institution. Use this value for the `institutionId` parameter.","examples":["institution:asb"],"type":"string"},"name":{"description":"The name of the institution.","examples":["ANZ","Kiwibank","Westpac"],"type":"string"},"products":{"description":"The personal loan products of this institution.","type":"array","items":{"additionalProperties":false,"type":"object","required":["id","name","rates"],"properties":{"id":{"pattern":"^product:","description":"The ID of the personal loan product.","examples":["product:asb:personal-loan"],"type":"string"},"name":{"description":"The name of the product that the institution uses.","examples":["Personal Loan"],"type":"string"},"rates":{"description":"The rates for this product.","type":"array","items":{"additionalProperties":false,"type":"object","required":["id","rate","plan","condition"],"properties":{"id":{"pattern":"^rate:","description":"The ID of the rate.","examples":["rate:anz:standard:18-months"],"type":"string"},"rate":{"description":"The interest rate for each year, in %. For example, `4.29` is 4.29 %.","examples":[4.29],"type":"number"},"plan":{"description":"The type of loan, for example, `Secured` or `Unsecured`. The value is `null` if the source does not give a type.","examples":["Secured"],"type":["string","null"]},"condition":{"description":"A condition for the rate, for example, a loan amount or a loan term. The value is `null` if the rate has no condition.","examples":["$3,000 to $50,000"],"type":["string","null"]}}}}}}}}}},"lastUpdated":{"description":"The date and time (UTC, ISO 8601) when the API collected this data from the source.","examples":["2021-08-01T00:00:00.000Z"],"type":"string"}}}}},"availableDates":{"description":"All dates that have a snapshot, in YYYY-MM-DD format. The list starts with the oldest date.","type":"array","items":{"examples":["2025-03-01"],"type":"string"}},"termsOfUse":{"description":"The terms of use for the data. The data can be incorrect. For correct rates, refer to the financial institution.","type":"string"},"timestamp":{"description":"The date and time (UTC, ISO 8601) when the server made this response.","examples":["2025-03-04T02:30:00.000Z"],"type":"string"},"message":{"description":"A message that tells you how to use this endpoint. The response contains this field only when the request has no dates.","examples":["Please specify a date or date range to retrieve time series data"],"type":"string"}}}}}},"400":{"description":"The request is not correct. For example, a date is not in YYYY-MM-DD format, or `startDate` is after `endDate`. Refer to the endpoint description for the date rules.","content":{"application/json":{"schema":{"additionalProperties":false,"description":"The request is not correct. For example, a date is not in YYYY-MM-DD format, or `startDate` is after `endDate`. Refer to the endpoint description for the date rules.","type":"object","required":["code","message"],"properties":{"code":{"description":"The HTTP status code of the response.","const":400,"type":"number"},"message":{"description":"A message that tells you about the error.","examples":["Invalid request parameters","Start date cannot be after end date"],"type":"string"}}}}}},"404":{"description":"The API did not find data for the parameters in the request. For example, there is no snapshot for the date. Use `availableDates` to find the dates that have a snapshot.","content":{"application/json":{"schema":{"additionalProperties":false,"description":"The API did not find data for the parameters in the request. For example, there is no snapshot for the date. Use `availableDates` to find the dates that have a snapshot.","type":"object","required":["code","message"],"properties":{"code":{"description":"The HTTP status code of the response.","const":404,"type":"number"},"message":{"description":"A message that tells you about the error.","examples":["No data available for date: 2025-03-01","Institution not found for date: 2025-03-01"],"type":"string"}}}}}},"500":{"description":"An error occurred on the server. Send the request again. If the error continues, refer to the `/api/v1/health` endpoint.","content":{"application/json":{"schema":{"additionalProperties":false,"description":"An error occurred on the server. Send the request again. If the error continues, refer to the `/api/v1/health` endpoint.","type":"object","required":["code","message"],"properties":{"code":{"description":"The HTTP status code of the response.","const":500,"type":"number"},"message":{"description":"A message that tells you about the error.","examples":["An error occurred while retrieving mortgage rates data"],"type":"string"}}}}}}}}},"/api/v1/personal-loan-rates/{institutionId}":{"get":{"operationId":"getPersonalLoanRatesByInstitution","tags":["Personal Loan Rates"],"summary":"Get personal loan rates for one institution","description":"This endpoint gets the newest personal loan rates for one institution. The response has the same structure as the list endpoint, but `data` contains only one institution.","parameters":[{"name":"institutionId","in":"path","required":true,"schema":{"examples":["institution:anz","institution:asb","institution:bnz","institution:kiwibank","institution:westpac"],"type":"string"},"description":"The ID of the institution. Use the `id` of an institution from the list endpoint. You can use upper-case or lower-case letters."}],"responses":{"200":{"description":"The newest personal loan rates.","content":{"application/json":{"schema":{"additionalProperties":false,"description":"The newest personal loan rates.","type":"object","required":["type","data","lastUpdated","termsOfUse","timestamp"],"properties":{"type":{"description":"The type of data. The value is always `PersonalLoanRates`.","const":"PersonalLoanRates","type":"string"},"data":{"title":"PersonalLoanRates","description":"The institutions and their personal loan rates.","type":"array","items":{"additionalProperties":false,"type":"object","required":["id","name","products"],"properties":{"id":{"pattern":"^institution:","description":"The ID of the institution. Use this value for the `institutionId` parameter.","examples":["institution:asb"],"type":"string"},"name":{"description":"The name of the institution.","examples":["ANZ","Kiwibank","Westpac"],"type":"string"},"products":{"description":"The personal loan products of this institution.","type":"array","items":{"additionalProperties":false,"type":"object","required":["id","name","rates"],"properties":{"id":{"pattern":"^product:","description":"The ID of the personal loan product.","examples":["product:asb:personal-loan"],"type":"string"},"name":{"description":"The name of the product that the institution uses.","examples":["Personal Loan"],"type":"string"},"rates":{"description":"The rates for this product.","type":"array","items":{"additionalProperties":false,"type":"object","required":["id","rate","plan","condition"],"properties":{"id":{"pattern":"^rate:","description":"The ID of the rate.","examples":["rate:anz:standard:18-months"],"type":"string"},"rate":{"description":"The interest rate for each year, in %. For example, `4.29` is 4.29 %.","examples":[4.29],"type":"number"},"plan":{"description":"The type of loan, for example, `Secured` or `Unsecured`. The value is `null` if the source does not give a type.","examples":["Secured"],"type":["string","null"]},"condition":{"description":"A condition for the rate, for example, a loan amount or a loan term. The value is `null` if the rate has no condition.","examples":["$3,000 to $50,000"],"type":["string","null"]}}}}}}}}}},"lastUpdated":{"description":"The date and time (UTC, ISO 8601) when the API collected this data from the source.","examples":["2021-08-01T00:00:00.000Z"],"type":"string"},"termsOfUse":{"description":"The terms of use for the data. The data can be incorrect. For correct rates, refer to the financial institution.","type":"string"},"timestamp":{"description":"The date and time (UTC, ISO 8601) when the server made this response.","examples":["2025-03-04T02:30:00.000Z"],"type":"string"}}}}}},"404":{"description":"The API did not find an institution with this ID.","content":{"application/json":{"schema":{"additionalProperties":false,"description":"The API did not find an institution with this ID.","type":"object","required":["code","message"],"properties":{"code":{"description":"The HTTP status code of the response.","const":404,"type":"number"},"message":{"description":"A message that tells you about the error.","examples":["Institution not found"],"type":"string"}}}}}},"500":{"description":"An error occurred on the server. Send the request again. If the error continues, refer to the `/api/v1/health` endpoint.","content":{"application/json":{"schema":{"additionalProperties":false,"description":"An error occurred on the server. Send the request again. If the error continues, refer to the `/api/v1/health` endpoint.","type":"object","required":["code","message"],"properties":{"code":{"description":"The HTTP status code of the response.","const":500,"type":"number"},"message":{"description":"A message that tells you about the error.","examples":["An error occurred while retrieving mortgage rates data"],"type":"string"}}}}}}}}},"/api/v1/car-loan-rates":{"get":{"operationId":"listCarLoanRates","tags":["Car Loan Rates"],"summary":"Get car loan rates for all institutions","description":"This endpoint gets the newest car loan rates for all institutions. Each institution contains products, and each product contains rates.\n\nA rate can have a plan, for example, `Secured`, and a condition, for example, a loan amount.\n\nUse this endpoint to compare car loan rates between institutions.","responses":{"200":{"description":"The newest car loan rates.","content":{"application/json":{"schema":{"additionalProperties":false,"description":"The newest car loan rates.","type":"object","required":["type","data","lastUpdated","termsOfUse","timestamp"],"properties":{"type":{"description":"The type of data. The value is always `CarLoanRates`.","const":"CarLoanRates","type":"string"},"data":{"title":"CarLoanRates","description":"The institutions and their car loan rates.","type":"array","items":{"additionalProperties":false,"type":"object","required":["id","name","products"],"properties":{"id":{"pattern":"^institution:","description":"The ID of the institution. Use this value for the `institutionId` parameter.","examples":["institution:asb"],"type":"string"},"name":{"description":"The name of the institution.","examples":["ANZ","Kiwibank","Westpac"],"type":"string"},"products":{"description":"The car loan products of this institution.","type":"array","items":{"additionalProperties":false,"type":"object","required":["id","name","rates"],"properties":{"id":{"pattern":"^product:","description":"The ID of the car loan product.","examples":["product:asb:car-loan"],"type":"string"},"name":{"description":"The name of the product that the institution uses.","examples":["Car Loan"],"type":"string"},"rates":{"description":"The rates for this product.","type":"array","items":{"additionalProperties":false,"type":"object","required":["id","rate","plan","condition"],"properties":{"id":{"pattern":"^rate:","description":"The ID of the rate.","examples":["rate:anz:standard:18-months"],"type":"string"},"rate":{"description":"The interest rate for each year, in %. For example, `4.29` is 4.29 %.","examples":[4.29],"type":"number"},"plan":{"description":"The type of loan, for example, `Secured` or `Unsecured`. The value is `null` if the source does not give a type.","examples":["Secured"],"type":["string","null"]},"condition":{"description":"A condition for the rate, for example, a loan amount or a loan term. The value is `null` if the rate has no condition.","examples":["$3,000 to $50,000"],"type":["string","null"]}}}}}}}}}},"lastUpdated":{"description":"The date and time (UTC, ISO 8601) when the API collected this data from the source.","examples":["2021-08-01T00:00:00.000Z"],"type":"string"},"termsOfUse":{"description":"The terms of use for the data. The data can be incorrect. For correct rates, refer to the financial institution.","type":"string"},"timestamp":{"description":"The date and time (UTC, ISO 8601) when the server made this response.","examples":["2025-03-04T02:30:00.000Z"],"type":"string"}}}}}},"500":{"description":"An error occurred on the server. Send the request again. If the error continues, refer to the `/api/v1/health` endpoint.","content":{"application/json":{"schema":{"additionalProperties":false,"description":"An error occurred on the server. Send the request again. If the error continues, refer to the `/api/v1/health` endpoint.","type":"object","required":["code","message"],"properties":{"code":{"description":"The HTTP status code of the response.","const":500,"type":"number"},"message":{"description":"A message that tells you about the error.","examples":["An error occurred while retrieving mortgage rates data"],"type":"string"}}}}}}}}},"/api/v1/car-loan-rates/time-series":{"get":{"operationId":"getCarLoanRatesTimeSeries","tags":["Car Loan Rates"],"summary":"Get historical car loan rates","description":"This endpoint gets historical snapshots of car loan rates. The API keeps one snapshot for each day (UTC) on which the data changed. Some dates do not have a snapshot.\n\nUse one of these options:\n\n- To get one snapshot, send `date`.\n- To get all snapshots in a range, send `startDate` and `endDate`. The range contains the two dates.\n- To get the list of dates that have a snapshot, send no dates. The `availableDates` field contains the list.\n\nDo not send `date` together with `startDate` or `endDate`.\n\nTo get only the data for one institution, send `institutionId`.","parameters":[{"name":"date","in":"query","required":false,"schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","examples":["2025-03-01"],"type":"string"},"description":"The date of one snapshot, in YYYY-MM-DD format (UTC). Do not use this parameter with `startDate` or `endDate`."},{"name":"startDate","in":"query","required":false,"schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","examples":["2025-01-01"],"type":"string"},"description":"The first date of the range, in YYYY-MM-DD format (UTC). You must also send `endDate`."},{"name":"endDate","in":"query","required":false,"schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","examples":["2025-03-01"],"type":"string"},"description":"The last date of the range, in YYYY-MM-DD format (UTC). You must also send `startDate`. This date must be on or after `startDate`."},{"name":"institutionId","in":"query","required":false,"schema":{"examples":["institution:anz"],"type":"string"},"description":"The ID of an institution. When you use this parameter, the response contains only the data for this institution. You can use upper-case or lower-case letters."}],"responses":{"200":{"description":"The snapshots for the dates in the request. If the request has no dates, `timeSeries` is empty and `availableDates` shows the dates that you can request.","content":{"application/json":{"schema":{"additionalProperties":false,"description":"The snapshots for the dates in the request. If the request has no dates, `timeSeries` is empty and `availableDates` shows the dates that you can request.","type":"object","required":["type","timeSeries","availableDates","termsOfUse","timestamp"],"properties":{"type":{"description":"The type of data. The value is always `CarLoanRatesTimeSeries`.","const":"CarLoanRatesTimeSeries","type":"string"},"timeSeries":{"description":"The snapshots. Each key is a snapshot date in YYYY-MM-DD format. Each value contains the data for that date.","type":"object","patternProperties":{"^(.*)$":{"additionalProperties":false,"type":"object","required":["type","data","lastUpdated"],"properties":{"type":{"description":"The type of data. The value is always `CarLoanRates`.","const":"CarLoanRates","type":"string"},"data":{"title":"CarLoanRates","description":"The institutions and their car loan rates.","type":"array","items":{"additionalProperties":false,"type":"object","required":["id","name","products"],"properties":{"id":{"pattern":"^institution:","description":"The ID of the institution. Use this value for the `institutionId` parameter.","examples":["institution:asb"],"type":"string"},"name":{"description":"The name of the institution.","examples":["ANZ","Kiwibank","Westpac"],"type":"string"},"products":{"description":"The car loan products of this institution.","type":"array","items":{"additionalProperties":false,"type":"object","required":["id","name","rates"],"properties":{"id":{"pattern":"^product:","description":"The ID of the car loan product.","examples":["product:asb:car-loan"],"type":"string"},"name":{"description":"The name of the product that the institution uses.","examples":["Car Loan"],"type":"string"},"rates":{"description":"The rates for this product.","type":"array","items":{"additionalProperties":false,"type":"object","required":["id","rate","plan","condition"],"properties":{"id":{"pattern":"^rate:","description":"The ID of the rate.","examples":["rate:anz:standard:18-months"],"type":"string"},"rate":{"description":"The interest rate for each year, in %. For example, `4.29` is 4.29 %.","examples":[4.29],"type":"number"},"plan":{"description":"The type of loan, for example, `Secured` or `Unsecured`. The value is `null` if the source does not give a type.","examples":["Secured"],"type":["string","null"]},"condition":{"description":"A condition for the rate, for example, a loan amount or a loan term. The value is `null` if the rate has no condition.","examples":["$3,000 to $50,000"],"type":["string","null"]}}}}}}}}}},"lastUpdated":{"description":"The date and time (UTC, ISO 8601) when the API collected this data from the source.","examples":["2021-08-01T00:00:00.000Z"],"type":"string"}}}}},"availableDates":{"description":"All dates that have a snapshot, in YYYY-MM-DD format. The list starts with the oldest date.","type":"array","items":{"examples":["2025-03-01"],"type":"string"}},"termsOfUse":{"description":"The terms of use for the data. The data can be incorrect. For correct rates, refer to the financial institution.","type":"string"},"timestamp":{"description":"The date and time (UTC, ISO 8601) when the server made this response.","examples":["2025-03-04T02:30:00.000Z"],"type":"string"},"message":{"description":"A message that tells you how to use this endpoint. The response contains this field only when the request has no dates.","examples":["Please specify a date or date range to retrieve time series data"],"type":"string"}}}}}},"400":{"description":"The request is not correct. For example, a date is not in YYYY-MM-DD format, or `startDate` is after `endDate`. Refer to the endpoint description for the date rules.","content":{"application/json":{"schema":{"additionalProperties":false,"description":"The request is not correct. For example, a date is not in YYYY-MM-DD format, or `startDate` is after `endDate`. Refer to the endpoint description for the date rules.","type":"object","required":["code","message"],"properties":{"code":{"description":"The HTTP status code of the response.","const":400,"type":"number"},"message":{"description":"A message that tells you about the error.","examples":["Invalid request parameters","Start date cannot be after end date"],"type":"string"}}}}}},"404":{"description":"The API did not find data for the parameters in the request. For example, there is no snapshot for the date. Use `availableDates` to find the dates that have a snapshot.","content":{"application/json":{"schema":{"additionalProperties":false,"description":"The API did not find data for the parameters in the request. For example, there is no snapshot for the date. Use `availableDates` to find the dates that have a snapshot.","type":"object","required":["code","message"],"properties":{"code":{"description":"The HTTP status code of the response.","const":404,"type":"number"},"message":{"description":"A message that tells you about the error.","examples":["No data available for date: 2025-03-01","Institution not found for date: 2025-03-01"],"type":"string"}}}}}},"500":{"description":"An error occurred on the server. Send the request again. If the error continues, refer to the `/api/v1/health` endpoint.","content":{"application/json":{"schema":{"additionalProperties":false,"description":"An error occurred on the server. Send the request again. If the error continues, refer to the `/api/v1/health` endpoint.","type":"object","required":["code","message"],"properties":{"code":{"description":"The HTTP status code of the response.","const":500,"type":"number"},"message":{"description":"A message that tells you about the error.","examples":["An error occurred while retrieving mortgage rates data"],"type":"string"}}}}}}}}},"/api/v1/car-loan-rates/{institutionId}":{"get":{"operationId":"getCarLoanRatesByInstitution","tags":["Car Loan Rates"],"summary":"Get car loan rates for one institution","description":"This endpoint gets the newest car loan rates for one institution. The response has the same structure as the list endpoint, but `data` contains only one institution.","parameters":[{"name":"institutionId","in":"path","required":true,"schema":{"examples":["institution:anz","institution:asb","institution:bnz","institution:kiwibank","institution:westpac"],"type":"string"},"description":"The ID of the institution. Use the `id` of an institution from the list endpoint. You can use upper-case or lower-case letters."}],"responses":{"200":{"description":"The newest car loan rates.","content":{"application/json":{"schema":{"additionalProperties":false,"description":"The newest car loan rates.","type":"object","required":["type","data","lastUpdated","termsOfUse","timestamp"],"properties":{"type":{"description":"The type of data. The value is always `CarLoanRates`.","const":"CarLoanRates","type":"string"},"data":{"title":"CarLoanRates","description":"The institutions and their car loan rates.","type":"array","items":{"additionalProperties":false,"type":"object","required":["id","name","products"],"properties":{"id":{"pattern":"^institution:","description":"The ID of the institution. Use this value for the `institutionId` parameter.","examples":["institution:asb"],"type":"string"},"name":{"description":"The name of the institution.","examples":["ANZ","Kiwibank","Westpac"],"type":"string"},"products":{"description":"The car loan products of this institution.","type":"array","items":{"additionalProperties":false,"type":"object","required":["id","name","rates"],"properties":{"id":{"pattern":"^product:","description":"The ID of the car loan product.","examples":["product:asb:car-loan"],"type":"string"},"name":{"description":"The name of the product that the institution uses.","examples":["Car Loan"],"type":"string"},"rates":{"description":"The rates for this product.","type":"array","items":{"additionalProperties":false,"type":"object","required":["id","rate","plan","condition"],"properties":{"id":{"pattern":"^rate:","description":"The ID of the rate.","examples":["rate:anz:standard:18-months"],"type":"string"},"rate":{"description":"The interest rate for each year, in %. For example, `4.29` is 4.29 %.","examples":[4.29],"type":"number"},"plan":{"description":"The type of loan, for example, `Secured` or `Unsecured`. The value is `null` if the source does not give a type.","examples":["Secured"],"type":["string","null"]},"condition":{"description":"A condition for the rate, for example, a loan amount or a loan term. The value is `null` if the rate has no condition.","examples":["$3,000 to $50,000"],"type":["string","null"]}}}}}}}}}},"lastUpdated":{"description":"The date and time (UTC, ISO 8601) when the API collected this data from the source.","examples":["2021-08-01T00:00:00.000Z"],"type":"string"},"termsOfUse":{"description":"The terms of use for the data. The data can be incorrect. For correct rates, refer to the financial institution.","type":"string"},"timestamp":{"description":"The date and time (UTC, ISO 8601) when the server made this response.","examples":["2025-03-04T02:30:00.000Z"],"type":"string"}}}}}},"404":{"description":"The API did not find an institution with this ID.","content":{"application/json":{"schema":{"additionalProperties":false,"description":"The API did not find an institution with this ID.","type":"object","required":["code","message"],"properties":{"code":{"description":"The HTTP status code of the response.","const":404,"type":"number"},"message":{"description":"A message that tells you about the error.","examples":["Institution not found"],"type":"string"}}}}}},"500":{"description":"An error occurred on the server. Send the request again. If the error continues, refer to the `/api/v1/health` endpoint.","content":{"application/json":{"schema":{"additionalProperties":false,"description":"An error occurred on the server. Send the request again. If the error continues, refer to the `/api/v1/health` endpoint.","type":"object","required":["code","message"],"properties":{"code":{"description":"The HTTP status code of the response.","const":500,"type":"number"},"message":{"description":"A message that tells you about the error.","examples":["An error occurred while retrieving mortgage rates data"],"type":"string"}}}}}}}}},"/api/v1/credit-card-rates":{"get":{"operationId":"listCreditCardRates","tags":["Credit Card Rates"],"summary":"Get credit card rates for all issuers","description":"This endpoint gets the newest credit card rates and fees for all issuers. Each issuer contains plans.\n\nEach plan has interest rates for purchases, cash advances, and balance transfers. It also has a card fee and an interest-free period.\n\nUse this endpoint to compare credit cards between issuers.","responses":{"200":{"description":"The newest credit card rates and fees.","content":{"application/json":{"schema":{"additionalProperties":false,"description":"The newest credit card rates and fees.","type":"object","required":["type","data","lastUpdated","termsOfUse","timestamp"],"properties":{"type":{"description":"The type of data. The value is always `CreditCardRates`.","const":"CreditCardRates","type":"string"},"data":{"title":"CreditCardRates","description":"The issuers and their credit card plans.","type":"array","items":{"additionalProperties":false,"type":"object","required":["id","name","plans"],"properties":{"id":{"pattern":"^issuer:","description":"The ID of the credit card issuer. Use this value for the `issuerId` parameter.","examples":["issuer:anz"],"type":"string"},"name":{"description":"The name of the issuer.","examples":["Amex","Gem"],"type":"string"},"plans":{"description":"The credit card plans of this issuer.","type":"array","items":{"additionalProperties":false,"type":"object","required":["id","name","interestFreePeriodInMonths","primaryFeeNZD","balanceTransferRate","balanceTransferPeriod","cashAdvanceRate","purchaseRate"],"properties":{"id":{"pattern":"^plan:","description":"The ID of the credit card plan.","examples":["plan:amex:airpoint-card"],"type":"string"},"name":{"description":"The name of the plan that the issuer uses.","examples":["Airpoint Card"],"type":"string"},"interestFreePeriodInMonths":{"description":"The longest interest-free period for purchases. The field name shows months, but the value is in days. For example, `55` is 55 days. The value is `null` if the plan has no interest-free period.","examples":[55],"type":["number","null"]},"primaryFeeNZD":{"description":"The card fee for the primary cardholder, in New Zealand dollars (NZD). The value is `null` if the source does not give a fee.","examples":[0,149],"type":["number","null"]},"balanceTransferRate":{"description":"The interest rate for a balance transfer, in %. The `balanceTransferPeriod` field gives the period of this rate. The value is `null` if the source does not give a rate.","examples":[0,5.95],"type":["number","null"]},"balanceTransferPeriod":{"description":"The period of the balance transfer rate, as text. The value is `null` if the source does not give a period.","examples":["6 months"],"type":["string","null"]},"cashAdvanceRate":{"description":"The interest rate for a cash advance, in % for each year. The value is `null` if the source does not give a rate.","examples":[0,21.95],"type":["number","null"]},"purchaseRate":{"description":"The interest rate for purchases, in % for each year. The value is `null` if the source does not give a rate.","examples":[0,21.95],"type":["number","null"]}}}}}}},"lastUpdated":{"description":"The date and time (UTC, ISO 8601) when the API collected this data from the source.","examples":["2021-08-01T00:00:00.000Z"],"type":"string"},"termsOfUse":{"description":"The terms of use for the data. The data can be incorrect. For correct rates, refer to the financial institution.","type":"string"},"timestamp":{"description":"The date and time (UTC, ISO 8601) when the server made this response.","examples":["2025-03-04T02:30:00.000Z"],"type":"string"}}}}}},"500":{"description":"An error occurred on the server. Send the request again. If the error continues, refer to the `/api/v1/health` endpoint.","content":{"application/json":{"schema":{"additionalProperties":false,"description":"An error occurred on the server. Send the request again. If the error continues, refer to the `/api/v1/health` endpoint.","type":"object","required":["code","message"],"properties":{"code":{"description":"The HTTP status code of the response.","const":500,"type":"number"},"message":{"description":"A message that tells you about the error.","examples":["An error occurred while retrieving mortgage rates data"],"type":"string"}}}}}}}}},"/api/v1/credit-card-rates/time-series":{"get":{"operationId":"getCreditCardRatesTimeSeries","tags":["Credit Card Rates"],"summary":"Get historical credit card rates","description":"This endpoint gets historical snapshots of credit card rates. The API keeps one snapshot for each day (UTC) on which the data changed. Some dates do not have a snapshot.\n\nUse one of these options:\n\n- To get one snapshot, send `date`.\n- To get all snapshots in a range, send `startDate` and `endDate`. The range contains the two dates.\n- To get the list of dates that have a snapshot, send no dates. The `availableDates` field contains the list.\n\nDo not send `date` together with `startDate` or `endDate`.\n\nTo get only the data for one issuer, send `issuerId`.","parameters":[{"name":"date","in":"query","required":false,"schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","examples":["2025-03-01"],"type":"string"},"description":"The date of one snapshot, in YYYY-MM-DD format (UTC). Do not use this parameter with `startDate` or `endDate`."},{"name":"startDate","in":"query","required":false,"schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","examples":["2025-01-01"],"type":"string"},"description":"The first date of the range, in YYYY-MM-DD format (UTC). You must also send `endDate`."},{"name":"endDate","in":"query","required":false,"schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}$","examples":["2025-03-01"],"type":"string"},"description":"The last date of the range, in YYYY-MM-DD format (UTC). You must also send `startDate`. This date must be on or after `startDate`."},{"name":"issuerId","in":"query","required":false,"schema":{"examples":["issuer:anz"],"type":"string"},"description":"The ID of a credit card issuer. When you use this parameter, the response contains only the data for this issuer. You can use upper-case or lower-case letters."}],"responses":{"200":{"description":"The snapshots for the dates in the request. If the request has no dates, `timeSeries` is empty and `availableDates` shows the dates that you can request.","content":{"application/json":{"schema":{"additionalProperties":false,"description":"The snapshots for the dates in the request. If the request has no dates, `timeSeries` is empty and `availableDates` shows the dates that you can request.","type":"object","required":["type","timeSeries","availableDates","termsOfUse","timestamp"],"properties":{"type":{"description":"The type of data. The value is always `CreditCardRatesTimeSeries`.","const":"CreditCardRatesTimeSeries","type":"string"},"timeSeries":{"description":"The snapshots. Each key is a snapshot date in YYYY-MM-DD format. Each value contains the data for that date.","type":"object","patternProperties":{"^(.*)$":{"additionalProperties":false,"type":"object","required":["type","data","lastUpdated"],"properties":{"type":{"description":"The type of data. The value is always `CreditCardRates`.","const":"CreditCardRates","type":"string"},"data":{"title":"CreditCardRates","description":"The issuers and their credit card plans.","type":"array","items":{"additionalProperties":false,"type":"object","required":["id","name","plans"],"properties":{"id":{"pattern":"^issuer:","description":"The ID of the credit card issuer. Use this value for the `issuerId` parameter.","examples":["issuer:anz"],"type":"string"},"name":{"description":"The name of the issuer.","examples":["Amex","Gem"],"type":"string"},"plans":{"description":"The credit card plans of this issuer.","type":"array","items":{"additionalProperties":false,"type":"object","required":["id","name","interestFreePeriodInMonths","primaryFeeNZD","balanceTransferRate","balanceTransferPeriod","cashAdvanceRate","purchaseRate"],"properties":{"id":{"pattern":"^plan:","description":"The ID of the credit card plan.","examples":["plan:amex:airpoint-card"],"type":"string"},"name":{"description":"The name of the plan that the issuer uses.","examples":["Airpoint Card"],"type":"string"},"interestFreePeriodInMonths":{"description":"The longest interest-free period for purchases. The field name shows months, but the value is in days. For example, `55` is 55 days. The value is `null` if the plan has no interest-free period.","examples":[55],"type":["number","null"]},"primaryFeeNZD":{"description":"The card fee for the primary cardholder, in New Zealand dollars (NZD). The value is `null` if the source does not give a fee.","examples":[0,149],"type":["number","null"]},"balanceTransferRate":{"description":"The interest rate for a balance transfer, in %. The `balanceTransferPeriod` field gives the period of this rate. The value is `null` if the source does not give a rate.","examples":[0,5.95],"type":["number","null"]},"balanceTransferPeriod":{"description":"The period of the balance transfer rate, as text. The value is `null` if the source does not give a period.","examples":["6 months"],"type":["string","null"]},"cashAdvanceRate":{"description":"The interest rate for a cash advance, in % for each year. The value is `null` if the source does not give a rate.","examples":[0,21.95],"type":["number","null"]},"purchaseRate":{"description":"The interest rate for purchases, in % for each year. The value is `null` if the source does not give a rate.","examples":[0,21.95],"type":["number","null"]}}}}}}},"lastUpdated":{"description":"The date and time (UTC, ISO 8601) when the API collected this data from the source.","examples":["2021-08-01T00:00:00.000Z"],"type":"string"}}}}},"availableDates":{"description":"All dates that have a snapshot, in YYYY-MM-DD format. The list starts with the oldest date.","type":"array","items":{"examples":["2025-03-01"],"type":"string"}},"termsOfUse":{"description":"The terms of use for the data. The data can be incorrect. For correct rates, refer to the financial institution.","type":"string"},"timestamp":{"description":"The date and time (UTC, ISO 8601) when the server made this response.","examples":["2025-03-04T02:30:00.000Z"],"type":"string"},"message":{"description":"A message that tells you how to use this endpoint. The response contains this field only when the request has no dates.","examples":["Please specify a date or date range to retrieve time series data"],"type":"string"}}}}}},"400":{"description":"The request is not correct. For example, a date is not in YYYY-MM-DD format, or `startDate` is after `endDate`. Refer to the endpoint description for the date rules.","content":{"application/json":{"schema":{"additionalProperties":false,"description":"The request is not correct. For example, a date is not in YYYY-MM-DD format, or `startDate` is after `endDate`. Refer to the endpoint description for the date rules.","type":"object","required":["code","message"],"properties":{"code":{"description":"The HTTP status code of the response.","const":400,"type":"number"},"message":{"description":"A message that tells you about the error.","examples":["Invalid request parameters","Start date cannot be after end date"],"type":"string"}}}}}},"404":{"description":"The API did not find data for the parameters in the request. For example, there is no snapshot for the date. Use `availableDates` to find the dates that have a snapshot.","content":{"application/json":{"schema":{"additionalProperties":false,"description":"The API did not find data for the parameters in the request. For example, there is no snapshot for the date. Use `availableDates` to find the dates that have a snapshot.","type":"object","required":["code","message"],"properties":{"code":{"description":"The HTTP status code of the response.","const":404,"type":"number"},"message":{"description":"A message that tells you about the error.","examples":["No data available for date: 2025-03-01","Institution not found for date: 2025-03-01"],"type":"string"}}}}}},"500":{"description":"An error occurred on the server. Send the request again. If the error continues, refer to the `/api/v1/health` endpoint.","content":{"application/json":{"schema":{"additionalProperties":false,"description":"An error occurred on the server. Send the request again. If the error continues, refer to the `/api/v1/health` endpoint.","type":"object","required":["code","message"],"properties":{"code":{"description":"The HTTP status code of the response.","const":500,"type":"number"},"message":{"description":"A message that tells you about the error.","examples":["An error occurred while retrieving mortgage rates data"],"type":"string"}}}}}}}}},"/api/v1/credit-card-rates/{issuerId}":{"get":{"operationId":"getCreditCardRatesByIssuer","tags":["Credit Card Rates"],"summary":"Get credit card rates for one issuer","description":"This endpoint gets the newest credit card rates for one issuer. The response has the same structure as the list endpoint, but `data` contains only one issuer.","parameters":[{"name":"issuerId","in":"path","required":true,"schema":{"examples":["issuer:anz","issuer:amex","issuer:gem"],"type":"string"},"description":"The ID of the credit card issuer. Use the `id` of an issuer from the list endpoint. You can use upper-case or lower-case letters."}],"responses":{"200":{"description":"The newest credit card rates and fees.","content":{"application/json":{"schema":{"additionalProperties":false,"description":"The newest credit card rates and fees.","type":"object","required":["type","data","lastUpdated","termsOfUse","timestamp"],"properties":{"type":{"description":"The type of data. The value is always `CreditCardRates`.","const":"CreditCardRates","type":"string"},"data":{"title":"CreditCardRates","description":"The issuers and their credit card plans.","type":"array","items":{"additionalProperties":false,"type":"object","required":["id","name","plans"],"properties":{"id":{"pattern":"^issuer:","description":"The ID of the credit card issuer. Use this value for the `issuerId` parameter.","examples":["issuer:anz"],"type":"string"},"name":{"description":"The name of the issuer.","examples":["Amex","Gem"],"type":"string"},"plans":{"description":"The credit card plans of this issuer.","type":"array","items":{"additionalProperties":false,"type":"object","required":["id","name","interestFreePeriodInMonths","primaryFeeNZD","balanceTransferRate","balanceTransferPeriod","cashAdvanceRate","purchaseRate"],"properties":{"id":{"pattern":"^plan:","description":"The ID of the credit card plan.","examples":["plan:amex:airpoint-card"],"type":"string"},"name":{"description":"The name of the plan that the issuer uses.","examples":["Airpoint Card"],"type":"string"},"interestFreePeriodInMonths":{"description":"The longest interest-free period for purchases. The field name shows months, but the value is in days. For example, `55` is 55 days. The value is `null` if the plan has no interest-free period.","examples":[55],"type":["number","null"]},"primaryFeeNZD":{"description":"The card fee for the primary cardholder, in New Zealand dollars (NZD). The value is `null` if the source does not give a fee.","examples":[0,149],"type":["number","null"]},"balanceTransferRate":{"description":"The interest rate for a balance transfer, in %. The `balanceTransferPeriod` field gives the period of this rate. The value is `null` if the source does not give a rate.","examples":[0,5.95],"type":["number","null"]},"balanceTransferPeriod":{"description":"The period of the balance transfer rate, as text. The value is `null` if the source does not give a period.","examples":["6 months"],"type":["string","null"]},"cashAdvanceRate":{"description":"The interest rate for a cash advance, in % for each year. The value is `null` if the source does not give a rate.","examples":[0,21.95],"type":["number","null"]},"purchaseRate":{"description":"The interest rate for purchases, in % for each year. The value is `null` if the source does not give a rate.","examples":[0,21.95],"type":["number","null"]}}}}}}},"lastUpdated":{"description":"The date and time (UTC, ISO 8601) when the API collected this data from the source.","examples":["2021-08-01T00:00:00.000Z"],"type":"string"},"termsOfUse":{"description":"The terms of use for the data. The data can be incorrect. For correct rates, refer to the financial institution.","type":"string"},"timestamp":{"description":"The date and time (UTC, ISO 8601) when the server made this response.","examples":["2025-03-04T02:30:00.000Z"],"type":"string"}}}}}},"404":{"description":"The API did not find an issuer with this ID.","content":{"application/json":{"schema":{"additionalProperties":false,"description":"The API did not find an issuer with this ID.","type":"object","required":["code","message"],"properties":{"code":{"description":"The HTTP status code of the response.","const":404,"type":"number"},"message":{"description":"A message that tells you about the error.","examples":["Issuer not found"],"type":"string"}}}}}},"500":{"description":"An error occurred on the server. Send the request again. If the error continues, refer to the `/api/v1/health` endpoint.","content":{"application/json":{"schema":{"additionalProperties":false,"description":"An error occurred on the server. Send the request again. If the error continues, refer to the `/api/v1/health` endpoint.","type":"object","required":["code","message"],"properties":{"code":{"description":"The HTTP status code of the response.","const":500,"type":"number"},"message":{"description":"A message that tells you about the error.","examples":["An error occurred while retrieving mortgage rates data"],"type":"string"}}}}}}}}},"/api/v1/mcp":{"post":{"operationId":"sendMcpMessage","tags":["MCP"],"summary":"Send an MCP message","description":"This endpoint is the MCP server of Rates API. MCP clients and AI agents use it to find and call the Rates API tools. The tools get the same data as the REST endpoints.\n\nThe endpoint uses the Streamable HTTP transport and JSON-RPC 2.0. Send each message in a `POST` request. A `GET` or `DELETE` request gets HTTP 405. The server does not use sessions.\n\nProtocol versions:\n\n- `2026-07-28` (current): Each request contains its protocol version, so you do not send `initialize`. Send the `MCP-Protocol-Version` and `Mcp-Method` headers. For `tools/call`, also send the `Mcp-Name` header. The headers must agree with the body.\n- `2025-11-25`, `2025-06-18`, `2025-03-26`, and `2024-11-05` (legacy): Send `initialize` first. Then send `tools/list` and `tools/call`.\n\nMethods:\n\n- `server/discover`: Gets the supported versions, the capabilities, and the server information.\n- `tools/list`: Gets the list of tools and their input schemas.\n- `tools/call`: Uses one tool with the arguments that you send.\n- `initialize` and `ping`: Only for the legacy versions.\n\nTools (all tools only read data, and all tool arguments are strings):\n\n- `list_mortgage_rates`: List mortgage rates\n- `get_mortgage_rates_by_institution`: Get mortgage rates for one institution\n- `get_mortgage_rates_time_series`: Get historical mortgage rates\n- `list_personal_loan_rates`: List personal loan rates\n- `get_personal_loan_rates_by_institution`: Get personal loan rates for one institution\n- `get_personal_loan_rates_time_series`: Get historical personal loan rates\n- `list_car_loan_rates`: List car loan rates\n- `get_car_loan_rates_by_institution`: Get car loan rates for one institution\n- `get_car_loan_rates_time_series`: Get historical car loan rates\n- `list_credit_card_rates`: List credit card rates\n- `get_credit_card_rates_by_issuer`: Get credit card rates for one issuer\n- `get_credit_card_rates_time_series`: Get historical credit card rates","externalDocs":{"description":"MCP guide","url":"https://www.ratesapi.nz/docs/api-reference/ai-integration"},"parameters":[{"name":"MCP-Protocol-Version","in":"header","required":false,"description":"The MCP protocol version. For `2026-07-28`, this header is necessary. Legacy clients for `2025-06-18` and later send the version that `initialize` gave.","schema":{"type":"string","enum":["2026-07-28","2025-11-25","2025-06-18","2025-03-26","2024-11-05"]},"example":"2026-07-28"},{"name":"Mcp-Method","in":"header","required":false,"description":"The JSON-RPC method. For `2026-07-28`, this header is necessary, and it must be the same as `method` in the body.","schema":{"type":"string"},"example":"tools/call"},{"name":"Mcp-Name","in":"header","required":false,"description":"The tool name. For a `2026-07-28` `tools/call` request, this header is necessary, and it must be the same as `params.name` in the body.","schema":{"type":"string"},"example":"list_mortgage_rates"}],"requestBody":{"required":true,"description":"One JSON-RPC 2.0 message. Clients that use `2025-03-26` can also send a batch (an array of messages).","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/McpMessage"},{"type":"array","items":{"$ref":"#/components/schemas/McpMessage"},"minItems":1,"description":"A batch of messages. Only for `2025-03-26`."}]},"examples":{"toolsCall":{"summary":"Call a tool","value":{"jsonrpc":"2.0","id":"rates-1","method":"tools/call","params":{"name":"list_mortgage_rates","arguments":{"termInMonths":"12"},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}},"toolsList":{"summary":"Get the list of tools","description":"Send `Mcp-Method: tools/list`, and no `Mcp-Name`.","value":{"jsonrpc":"2.0","id":"rates-2","method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}}}}}},"responses":{"200":{"description":"The JSON-RPC response. For a batch, the body is an array of responses. An internal error or a tool error also gets HTTP 200: the response contains `error`, or the result contains `isError: true`.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/McpResponse"},{"type":"array","items":{"$ref":"#/components/schemas/McpResponse"}}]},"example":{"jsonrpc":"2.0","id":"rates-1","result":{"resultType":"complete","content":[{"type":"text","text":"{\"type\":\"MortgageRates\",\"data\":[…]}"}],"structuredContent":{"type":"MortgageRates","data":[]}}}}}},"202":{"description":"The message is a notification, or the batch contains only notifications. The response has no body."},"400":{"description":"The server cannot use the request. The body is a JSON-RPC error response. The error code gives the cause:\n\n- `-32700`: The body is not JSON.\n- `-32600`: The client sends a batch with a version other than `2025-03-26`. For `2026-07-28`, a message that is not a correct JSON-RPC 2.0 request also gets this error.\n- `-32020`: A necessary header is missing, or it does not agree with the body.\n- `-32602`: A necessary `_meta` field is missing.\n- `-32022`: The server does not support the protocol version. The error data contains the supported versions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpResponse"},"example":{"jsonrpc":"2.0","id":"rates-1","error":{"code":-32020,"message":"Header mismatch: Missing required Mcp-Method header"}}}}},"404":{"description":"For `2026-07-28`, the method does not exist (error `-32601`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpResponse"},"example":{"jsonrpc":"2.0","id":"rates-1","error":{"code":-32601,"message":"Method not found: resources/list"}}}}}}}},"/api/v1/health":{"get":{"operationId":"getHealth","tags":["Health"],"summary":"Get the status of the API","description":"This endpoint shows if the API can read its database. Use this endpoint to make sure that the API operates correctly.\n\nThe API collects data each hour, but it saves a dataset only when the data changes. Thus, for each dataset, the response shows two times:\n\n- `lastUpdated` is the time of the last change to the data. This time can be old when the data is correct.\n- `lastChecked` is the time of the last correct data collection.\n\n`stale` is `true` when the API did not collect the dataset correctly in the last 3 hours. The `status` stays `ok` when a dataset is stale.","responses":{"200":{"description":"The API can read its database. The response shows the time of the last change and the time of the last data collection for each dataset.","content":{"application/json":{"schema":{"additionalProperties":false,"description":"The API can read its database. The response shows the time of the last change and the time of the last data collection for each dataset.","type":"object","required":["status","dataSets","timestamp"],"properties":{"status":{"description":"The status of the API. The value `ok` shows that the API can read its database.","const":"ok","type":"string"},"dataSets":{"description":"The datasets of the API. There is one item for each type of rate.","type":"array","items":{"additionalProperties":false,"type":"object","required":["dataType","lastUpdated","lastChecked","stale"],"properties":{"dataType":{"description":"The name of the dataset.","examples":["mortgage-rates"],"type":"string"},"lastUpdated":{"description":"The date and time (UTC) of the last change to this dataset, in YYYY-MM-DD HH:MM:SS format. This time does not change when the API collects the same data again.","examples":["2025-03-04 01:00:00"],"type":"string"},"lastChecked":{"description":"The date and time (UTC) of the last correct data collection for this dataset, in YYYY-MM-DD HH:MM:SS format. The API collects each dataset each hour, also when the data does not change. The value is `null` if the API has no record of a collection.","examples":["2025-03-05 09:00:00"],"type":["string","null"]},"stale":{"description":"The value is `true` if the API did not collect this dataset correctly in the last 3 hours. Then the data can be old. The value is `false` if the API collected the dataset in the last 3 hours. The value is `null` if `lastChecked` is `null`.","type":["boolean","null"]}}}},"timestamp":{"description":"The date and time (UTC, ISO 8601) when the server made this response.","examples":["2025-03-04T02:30:00.000Z"],"type":"string"}}}}}},"500":{"description":"The API cannot read its database.","content":{"application/json":{"schema":{"additionalProperties":false,"description":"The API cannot read its database.","type":"object","required":["status","message","timestamp"],"properties":{"status":{"description":"The status of the API. The value `error` shows that the API cannot read its database.","const":"error","type":"string"},"message":{"description":"A message that tells you about the error.","examples":["Unable to read data freshness"],"type":"string"},"timestamp":{"description":"The date and time (UTC, ISO 8601) when the server made this response.","examples":["2025-03-04T02:30:00.000Z"],"type":"string"}}}}}}}}}},"components":{"schemas":{"McpMessage":{"type":"object","required":["jsonrpc","method"],"properties":{"jsonrpc":{"description":"The JSON-RPC version.","const":"2.0","type":"string"},"id":{"description":"The ID of the request. The response contains the same ID. A message without an ID is a notification.","anyOf":[{"type":"string"},{"type":"integer"}]},"method":{"description":"The MCP method.","examples":["tools/call"],"type":"string"},"params":{"additionalProperties":true,"description":"The parameters of the method. For `2026-07-28`, `_meta` must contain `io.modelcontextprotocol/protocolVersion` and `io.modelcontextprotocol/clientCapabilities`.","type":"object","properties":{}}},"$id":"#/components/schemas/McpMessage"},"McpResponse":{"type":"object","required":["jsonrpc","id"],"properties":{"jsonrpc":{"description":"The JSON-RPC version.","const":"2.0","type":"string"},"id":{"description":"The ID of the request. It is `null` if the server cannot read the ID of the request.","anyOf":[{"type":"string"},{"type":"integer"},{"type":"null"}]},"result":{"additionalProperties":true,"description":"The result of the method. A response contains `result` or `error`, not both.","type":"object","properties":{}},"error":{"type":"object","required":["code","message"],"properties":{"code":{"description":"The JSON-RPC error code.","examples":[-32601],"type":"integer"},"message":{"description":"A short description of the error.","type":"string"},"data":{"description":"More information about the error."}}}},"$id":"#/components/schemas/McpResponse"}}}}