API version deprecation policy

How long do API versions live?

Short answer:
two years.

Every API version that is exactly two years old or older, will normally be deprecated. An API version enters its deprecation pending phase one and a half year after its release and six months before its canonical deprecation. It is possible that a version which is older than two years is still active at some point. This API version is still pending deprecation and its usage is strongly discouraged.

What happens to requests directed to deprecated API versions?

Short answer:
Requests to deprecated API versions are currently being served by version 20200405.

Requests to deprecated versions will return results from a newer version. This version is currently 20200405. The serving version is generally chosen to be as close to the deprecated version as possible. This is to minimize changes in object IDs (see section for differences in data between versions.) These requests should normally return valid (and more up-to-date) results (see section for fresh api versions.)

Thus, for example, if someone using your app does not update it on her device in time, she will continue to normally get valid (and better) results.

Requests to deprecated API versions are not being redirected. It is simply that results from an available version are returned. This is to avoid failing to serve clients that do not follow redirects. Instead an extra field is returned in the response (see the relevant section for deprecation status extra fields.)

How do I know when I am using a deprecated API version?

  • You should normally expect an API version deprecation every two years since its initial release date. This date is the version's name encoded in ISO format. So for example, a version named 19700101 would normally be deprecated on the 1st of January, 1972.

  • See the relevant section for detailed API version deprecation status.

  • If you still for any reason do not manage to update in time, once a version is deprecated, all API requests to that version will be served by a newer version, with an extra field indicating deprecation.

Deprecation status extra field

Every API request returns an is_deprecated field, that has three possible values:

  • yes: The version is deprecated. Returned results are from a newer supported version (currently 20200405).

  • pending: The version is still supported but is pending deprecation within six months or less from the time of the request. You should consider switching to a newer version.

  • no: The version that you are using is not deprecated or pending deprecation.

Observe for example, the value of the field is_deprecated for a request to a deprecated version:

View the response

Also notice that everything else is actually identical to the response for version 20200405:

View the response

Fresh API versions

How often can I expect a new API version?

Short answer:
Every three months.

Almost every three months, a new api version will be released. A new api version always has fresher data. Sometimes it might also include extra features. The major changes between versions are documented in release notes.

Are new API versions backwards compatible?

Short answer:
yes.

New versions are generally backwards compatible. This means that if you do an API query to the penultimate version, you should expect the same behaviour if you repeat the same query for the latest version. Backwards incompatible changes are very rare, but still possible. These changes will be documented in release notes, explicitly marked as backwards incompatible.

What changes in data might affect my queries?

Short answer:
Object ID changes

Regarding data, we try to minimise our object ID churn between releases. Nevertheless, although an identical ID is highly likely, in some cases it is not guaranteed. For example, if you want to find the top 10 sightseeing POIs for a location ID (for example London) for the latest version,

View the response

Whereas for the penultimate version 20210317:

View the response

See that for the returned POIs that are the same, ID is most likely the same.

Observe in the above queries, that results might differ a bit (ie different scores or different POIs etc). This is due to the fact that data has been updated and algorithms improved. Therefore, the results of the latest version should always be more accurate by the time of the query.

A stable ID, means that the location ID is the same for both versions (London). A non-stable ID would be an ID that would be for example London for version 20210615 and eg City_of_London for version 20210317.

Below is an extensive list of types that might or might not be changing IDs between API versions. You can consider that any type that is not explicitly mentioned in one of the lists below, is not expected to have any effect on the behaviour of your queries.

API types that are NOT guaranteed to preserve ID between versions

The following types are highly likely to preserve IDs between API versions, but not guaranteed:

API types that are guaranteed to preserve ID between versions

The following types are generally guaranteed to preserve IDs between API versions. Any backwards incompatible change is unlikely, but still possible. In case such a change ever occurs, it will be explicitly documented in release notes, marked as backwards incompatible.

  • tag_labels

    This type affects queries for other endpoints (such us poi), when using tag_labels parameter.

    Note that there are lots of tag labels, some of which are being generated dynamically and are not guaranteed to be preserved between versions. All tag labels that are listed in common tag labels endpoint, will be preserved. As a rule of thumb, new tag labels are often added to new versions, as our data gets richer. Nevertheless, new versions will support all older tag labels that are listed under common tag labels as well. Tag labels that are not listed in common tag labels and are dynamic (so possibly changing between versions) are generally descendants of cuisine, district and person. Note that the descendants of the above categories that are listed in common tag labels, are stable.

  • tour