API policy
How the API changes, and how you will hear about it.
Versioning
- The API is versioned in the path. Everything now is under
/v1. - /v1 stays stable. We may add new endpoints, new fields in responses, and new values where a field is already a list of values. Write your code to ignore fields it does not know.
- Breaking changes go in /v2. A breaking change is removing or renaming a field or endpoint, changing what a field means, or making a request stricter. We will not make one inside /v1.
- At least 90 days' notice before /v1 or any /v1 endpoint is retired, announced in the changelog and in a notice field in responses during the last 90 days.
Availability
There is no uptime guarantee and no support commitment on the free tier. We aim to keep the service running and fix problems fast. Status and /v1/health show when each data source last refreshed. Higher-limit arrangements, when they exist, will say what is promised.
Limits
Free (beta) keys: 1,000 requests a month and 10 a minute, for non-commercial use (see the terms and pricing). Beta limits may change with 30 days' notice. We may change limits with notice in the changelog; we will not lower a limit you rely on without at least 30 days' notice, except to stop abuse.
How we tell you
- Every change that affects you is in the changelog with its date, including every change to these policies.
- We cannot email you about changes, because we keep only a hash of your email address. Watch the changelog. During the last 90 days before anything is retired, responses will also carry a notice field saying so.