# Interest rates

Estimated market APR for each credit tier (published tier averages moved by the change in the Federal Reserve G.19 benchmark since), average credit-union and bank rates, and the manufacturer's financing offers for the model, nearest the ZIP first. With `creditScore`, `apr` is the estimate for that score.

## Endpoint

```
GET https://api.motorsdynamic.com/api/v2/apr/{vin}
```

## Plan and price

| Plan | Access | Price |
| --- | --- | --- |
| Free | No | not included |
| Growth | Yes | $0.005 per call |
| Scale | Yes | $0.003 per call |
| Enterprise | Yes | contract |

A call is billed when it answers 2xx. See [pricing](https://developers.motorsdynamic.com/pricing.md).

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `vin` | path | string | yes | 17-character VIN (case-insensitive). |
| `zip` | query | string | no | 5-digit ZIP code of a US state or DC. |
| `creditScore` | query | integer | no | Credit score; picks the credit tier. |
| `condition` | query | `new` or `used` | no | Which rate table to read. Default: the listing's condition. |

## Example request

curl:

```bash
curl "https://api.motorsdynamic.com/api/v2/apr/1HGCM82633A004352" \
  -H "x-api-key: $MD_API_KEY"
```

JavaScript:

```javascript
const res = await fetch("https://api.motorsdynamic.com/api/v2/apr/1HGCM82633A004352", {
  headers: { "x-api-key": process.env.MD_API_KEY },
});
if (!res.ok) throw new Error(`${res.status} ${(await res.json()).error}`);
const data = await res.json();
console.log(data);
```

Python:

```python
import os, requests

res = requests.get(
    "https://api.motorsdynamic.com/api/v2/apr/1HGCM82633A004352",
    headers={"x-api-key": os.environ["MD_API_KEY"]},
    timeout=10,
)
res.raise_for_status()
print(res.json())
```

## Response fields

| Field | Type | Description |
| --- | --- | --- |
| `meta` | object |  |
| `meta.default_term_months` | integer |  |
| `data` | object |  |
| `data.vin` | string |  |
| `data.vehicle` | object |  |
| `data.vehicle.year` | integer or null |  |
| `data.vehicle.make` | string or null |  |
| `data.vehicle.model` | string or null |  |
| `data.vehicle.trim` | string or null |  |
| `data.zip` | string or null |  |
| `data.state` | string or null |  |
| `data.product` | `new` or `used` |  |
| `data.credit_score` | integer or null |  |
| `data.apr` | object or null |  |
| `data.by_term` | object or null | The estimate for the credit score at each loan term the Fed publishes (months to percent). |
| `data.tiers[]` | array of object |  |
| `data.tiers[].tier` | `super_prime` or `prime` or `near_prime` or `subprime` or `deep_subprime` |  |
| `data.tiers[].score_low` | integer |  |
| `data.tiers[].score_high` | integer |  |
| `data.tiers[].apr` | number | Percent. |
| `data.tiers[].estimate` | `true` |  |
| `data.tiers[].terms` | object |  |
| `data.lender_averages[]` | array of object |  |
| `data.lender_averages[].lender_type` | `credit_union` or `bank` |  |
| `data.lender_averages[].term_months` | integer |  |
| `data.lender_averages[].apr` | number |  |
| `data.lender_averages[].observed_on` | string |  |
| `data.lender_averages[].source` | string |  |
| `data.lender_averages[].source_url` | string |  |
| `data.manufacturer_offers[]` | array of object |  |
| `data.manufacturer_offers[].offer_id` | integer |  |
| `data.manufacturer_offers[].title` | string or null |  |
| `data.manufacturer_offers[].trims` | array or null | Trims the offer names; null = the whole model. |
| `data.manufacturer_offers[].apr` | number |  |
| `data.manufacturer_offers[].term_months` | integer or null |  |
| `data.manufacturer_offers[].geography` | `same_zip` or `same_area` or `same_state` or `other_region` or `not_compared` |  |
| `data.manufacturer_offers[].postal_code` | string or null |  |
| `data.manufacturer_offers[].end_date` | string or null |  |
| `data.manufacturer_offers[].disclaimer` | string or null |  |
| `data.manufacturer_offers[].estimate` | `false` |  |
| `data.manufacturer_offers[].terms` | object |  |
| `data.disclosure` | string |  |

## Errors

| Status | Code | When |
| --- | --- | --- |
| 400 | `invalid_parameter` | A parameter is missing or malformed. The message names it. |
| 401 | `invalid_api_key` | The key is missing, revoked or mistyped. |
| 402 | `plan_required` | The endpoint is on a higher plan. The body names the plan and links to the upgrade. |
| 403 | `not_entitled` | The key may not read this dealer or source. |
| 404 | `not_found` | Nothing matches the identifier in the path. |
| 429 | `rate_limited or quota_exceeded` | Slow down (see `Retry-After`), or the Free monthly calls are used up. |
| 503 | `error` | See the message. |
| 504 | `query_timeout` | The query passed its 4 second budget. Narrow the filters. Not billed. |

Every error has the same body: `{ "error": "<code>", "message": "..." }`. Full list: [errors](https://developers.motorsdynamic.com/docs/errors.md).