API Versions and Retirement Policy

How our API versions work

Each of our APIs has a major version, which is part of its address (for example /Api/Geocode/V6/) and its version parameter. Within a version we make only changes that keep working clients working: corrections, faster or more accurate results, and new optional parameters.

Changes that could break a client, such as removing or renaming a parameter or an output field, changing an output field's type, or changing the order of CSV and TSV columns, come only in a new major version, or after notice under this policy.

How long older versions keep working

• An API version that customers still use keeps working for at least 6 months after we announce its retirement date.
• An API version that no customer has used in the last 12 months keeps working for at least 90 days after we announce its retirement date.
• An output format or a parameter within a version keeps working for at least 3 months after we announce its retirement.
• Until its retirement date, a retiring version keeps working as it does today. It receives security fixes only, and new features go into the current version.
• After the retirement date, requests to that version receive an error that names the version to use instead.

How we tell you

• An email to every account that used the version, format or parameter in the 12 months before the announcement.
• A notice on that version's documentation page, with its retirement date and a link to the guide for moving to the current version.
• An entry in What's new.
• On the retiring version's responses, the standard HTTP headers Deprecation and Sunset, so your software can notice too.

Current versions

Exceptions

If a security problem requires it, we may change or turn off a version, format or parameter sooner. We will tell affected accounts as soon as we can, and explain why.

This policy and our Terms of Use

This policy describes how we plan to manage changes to our APIs. Our Terms of Use still apply.