Skip to content

Changelog

Every change you can see in the API, newest first. Follow it in a feed reader: Atom feed.

  1. Added

    Guides: diverted stretches on a stage

    GET /api/guides/v1/guides/{id}: a stage's stays.closures[] can now have state "diverted": the stretch from from_km to to_km is closed but walkable by an official signed diversion. It may carry extra_minutes and extra_km, the diversion's extra time and distance as the operator publishes them; each is absent when not published. Unlike detour, which is a whole stage walked on an official detour with its own figures, a diversion covers part of a stage and adds to its figures. Treat it as open with a note, not as a closure.

  2. Fixed

    Elevation profile reads gorges as route analysis does

    POST /v1/elevation-profile now applies the gorge rule that route analysis applies: on a line along a gorge-flagged path, where the 30 m terrain cannot follow the path between cliff and river, those heights are read on the local line instead. On 6 of 30 lines in our consistency suite the profile had named a different climb method than route analysis, and on two of them read 5 and 27 m more climb; all 30 now agree on climb, method and extremes. The profile finds gorge paths within 25 m of the line rather than by matching the line to the map, so a line beside a gorge path, or a GPS track far off it, can still differ slightly; if the lookup takes longer than 0.3 s the profile is read without the rule. Lines without a gorge are unchanged; elevation.method names +gorge40o25 where the rule applied.

  3. Changed

    Races: course descents re-derived

    GET /api/races/v1/races: descent_m changed on 319 courses (in two passes on 13 October). Where the organizer publishes no descent, it is now the stated climb minus the course file's own net rise, which does not depend on how the heights are smoothed. Before, it was the file's raw descent, which read 20 to 25 % short on long loops (a 6,550 m loop read 5,230 m down). An organizer's stated descent is never overwritten. The record's shape is unchanged.

  4. Changed

    Guides: 63 stages renamed, their old ids kept as former_ids

    On 12 October 63 stages of the automatic guides were renamed so each ends at a real place (a village, a station, a hut) rather than a road or a car park, so their ids in GET /api/guides/v1/guides/{id} changed and their old page addresses now redirect. Each stage that had other ids now lists them in former_ids, so an id you stored still finds its stage. Stage figures were also refreshed to the current terrain and climb method (climb, descent and time; distances are unchanged).

  5. Changed

    GPX simplify keeps the climb closer

    POST /v1/gpx/simplify with keep_climb (the default): in tolerance mode no dropped point now sits more than 3 m off the kept climb (it was 5 m), and in budget mode a metre of climb now weighs as much as 4 m of sideways shape (it was 3). Measured on 23 courses, three of our own and 20 organizers' files, the climb of a simplified file then stays within 3 % of the original's at the recommended 10 m and at 1,000 points on all 23, where before it did on 19 and 22.

  6. Added

    Pace plan: time and effort at your checkpoints

    POST /v1/pace-plan takes checkpoints: up to 200 distances along the course in metres, for aid stations or cut-offs. The answer gives, for each, the distance read, the climb and descent so far, the effort and the cumulative time, shared exactly as the splits share the target: at a split boundary the time equals that split's. Without checkpoints the answer is unchanged.

  7. Fixed

    Heights in the southern Caucasus

    Elevation, route analysis and the terrain tiles read 0 m across Armenia, Azerbaijan, southern Georgia and the neighbouring areas around Kars and Tabriz (Yerevan, Tbilisi, Ganja). Those areas are now filled from open SRTM heights: Yerevan reads about 1,000 m, Tbilisi 607 m and Ganja 425 m, and routes there climb as they should.

  8. Added

    Search finds cable-car stations, tram stops and ferry landings

    Place search now holds cable-car and gondola stations, tram stops and ferry landings, one place per stop however many platforms it has, and places of worship with a Wikidata entry, trailheads and stadiums. A query that finds nothing as a whole is read as name and place without the comma ("Bort Grindelwald"), and a village can be the place when the name is found around it. A trail of the same name elsewhere no longer outranks a place of that name in the map view.

  9. Fixed

    Round trips with a climb target keep the length you asked for

    A loop that reproduced the climb could rank first however long it ran: 12 km asked for, 22.6 km answered. The asked length is now a hard band: loops within 10 % of it come first, the one that reproduces the climb leading them. When none within the length holds the climb, the best of them comes back with met false and climb_target.reason says so, and whether a longer loop may.

  10. Added

    Round trips: rehearse a continuous climb

    POST /v1/roundtrips takes climb_target: { ascent_m, distance_m?, grade_pct? } for hike and run, for example a race's largest continuous ascent from course sections. The search leans uphill, loops through a summit within reach join the candidates, and the loops come back ordered by how well their longest continuous climb reproduces the target. Each loop says what it reproduces, dimension by dimension (climb and length within 20 %, grade within 2 points), and the answer says plainly when nothing within reach rises enough. The length and repeat rules and each loop's status are unchanged.

  11. Fixed

    Climb on moderately noisy lines: less phantom climb

    Lines whose terrain jitters only moderately but whose climb lives mostly in short wobbles (Stevenson stage 9, the Pembrokeshire coast) read 12 to 36 % above national lidar, because the noise guard only started to cut on clearly noisy series. It now also cuts there, in proportion to the noise: those stages read within 3 % of lidar. No line on the lidar bar moves. Method names are unchanged; course sections' segmentation_version names route-adaptive50-100m+denoise3+flat4.

  12. Fixed

    Climb on steep alpine flanks: the noise guard no longer cuts real rises

    The noise guard introduced earlier today also took real climb on steep alpine traverses, where the terrain model is as noisy as on Madeira's cliffs but every rise is real: Tour Monte Rosa's Europaweg stages read 6 to 17 % under national lidar. The guard's threshold now scales with how much of a line's climb lives in short wavelengths, so those stages read within 6 % and the long Madeira race lines within 4 %, while the coast lines the guard was made for keep it. Short, nearly level levadas that read 0 m now keep their small real rises. Method names are unchanged; course sections' segmentation_version names route-adaptive50-100m+denoise2+flat4.

  13. Changed

    Climb on noisy terrain: a noise guard

    Where the terrain model's heights jitter around the ground (rough coast and cliffs, as on Madeira), route analysis, the elevation profile, /v1/route, round trips, course sections and the pace plan now repair outliers and count a rise only once it passes the series' own noise. The method says so: route-smoothed-50m+denoise+flat4 (or 100m). Checked against national lidar like for like: Madeira's race lines that read up to twice their climb now read within about 10 %, and no line on the lidar set reads worse. Quiet series, most alpine and every road course, read exactly as before. If you validate method names strictly, accept the two new values.

  14. Changed

    Pace plan: one climb with route analysis

    POST /v1/pace-plan now counts climb by the route method, as route analysis and course sections do: heights smoothed over ±100 m (±50 m on lines that climb 25 m a kilometre or more), rises and falls under 4 m on flat stretches ignored, booked where they happen. course.gain_m therefore equals route analysis's climb on the same heights, and sections.totals.ascent_m equals course.gain_m; course.smoothing names the method. On mountain lines the plan's climb rises by up to about 10 %, on flat lines it falls (it used to count every small rise); the splits are shared out by that climb, so a target time stays the same and a flat-pace finish moves a little. The plan also reads heights as route analysis does: terrain samples every 20 m, and a file's own heights only where they pass its check against the ground (a new unknown, recorded_heights_rejected, says why when they do not). The race pace calculator and the Pace & Split Calculator count the same way.

  15. Changed

    Climb on hilly lines: read on a narrower window

    Where route analysis, the elevation profile, /v1/route, round trips and course sections read heights from the terrain model, a line that climbs 25 m a kilometre or more is now smoothed over ±50 m instead of ±100 m, and its method says so: elevation.method (and ascent_method, sections.height_method) is route-smoothed-50m+flat4, or route-smoothed-50m+gorge40o25+flat4 with the gorge rule. Measured against national lidar on 27 stable hilly lines, the climb is now within 10 % (or 50 m) on 26 of them, against 15 before, and no line reads worse; hilly climbs typically rise 5 to 15 %. Flat and rolling lines read exactly as before, under the old name. course-sections segmentation_version names the rule (route-adaptive50-100m+flat4); section boundaries are unchanged. Walking times and the pace plan keep their own basis. If you validate method names strictly, accept the two new values.

  16. Added

    Open aerial imagery as a public layer

    GET /tiles/v1/imagery/tilejson describes one raster layer of official national orthophotos (Switzerland, France, Austria, Spain, Bavaria, the contiguous US, South Tyrol, Slovenia, Trentino, Japan) and our Sentinel-2 summer mosaic for 16 trail regions, each cut at its border and transparent elsewhere (zooms 8–19, WebP). Each source keeps its open licence, with no restriction added; show the credits of the sources in view (GET /tiles/v1/imagery/credits). /tiles/v1/imagery/coverage.geojson maps where each source covers. Unmetered, like all map tiles (imagery/1).

  17. Added

    A topographic outdoor style

    GET /styles/current/topo.json is a second MapLibre style for hiking and running maps: relief, contours with 100 m index lines and heights, cliffs and ridges, scree and glaciers, waymarked trails by difficulty (SAC scale), huts, water, passes and peaks. It needs no sprite and two fonts, its sources are pinned to release addresses (cacheable), and it is re-pinned at every weekly release; /styles/v/<release>/topo.json is a fixed version (artifacts.styles.topo in the manifest). Layer ids are part of the contract (topo-style/1). Unmetered, like all map tiles and styles.

  18. Fixed

    Pace plan sections: how far their climb sits below the plan's

    In the pace plan's sections mode, sections.totals.ascent_m (the route method: rises under 4 m on flat ground do not count) is never higher than course.gain_m (every smoothed rise). The reference said "a little lower": that holds within 2 % on mountain lines, but on rolling or flat lines it is 4 to 60 % lower. Show one of the two, named. No answer changed.

  19. Added

    Course sections in route analysis and pace plans

    POST /v1/route-analysis takes sections: true and answers the line's course sections (course-sections/1): its climbs, descents and the ground between them, the largest continuous ascent, the longest descent and the steepest 500 m and kilometre, each with its share of the moving time. The same definition the race pages, the Course Analyzer and the race plan use; segmentation_version names every threshold. POST /v1/pace-plan takes sections: true too and adds each section's time in your plan (section_times). Without the field, answers are as before.

  20. Added

    Server-Timing on every answer

    Every metered answer now carries Server-Timing: origin;dur=<ms>, the time the TrailSplits service took to start its answer. The rest of what you measure is the network between you and the API, so you can tell a slow call from a slow path. Browsers read it too (Timing-Allow-Origin: *).

  21. Added

    Route analysis: the published signpost convention, where there is one

    time.models[] in route analysis gains trailsplits-hike-published/1: the signpost convention a publisher states for its own trails, beside the TrailSplits moving time (which stays time.minutes). First in Trentino, from the Società degli Alpinisti Tridentini (SAT): when at least half of the line lies in the area of SAT’s fitted sections, convention gives its factors, an 80 % interval, the held-out check, the licence and the attribution. Elsewhere, Switzerland included, convention is null with the label "No published convention here" and the reason. SAT data: ODbL 1.0 and DbCL 1.0, © Società degli Alpinisti Tridentini (SAT); the attribution is in each answer.

  22. Added

    Errors say which input, what to do, and link their code

    Every refusal from the API now links its code on /api/errors (docs). Where they apply it also names the offending input (field, e.g. hills or waypoints[3]), gives the bound crossed and what was sent as numbers (limit, got), one sentence on what to do (hint), the seconds to wait with 429 and 503 (retry_after, equal to Retry-After) and an id to quote with 5xx (request_id). A broken JSON body is now invalid_json. Existing fields are unchanged.

  23. Changed

    Route climb from terrain samples

    POST /v1/route, round trips and route analysis now take ascent, the legs’ climb and the time from terrain samples along the line (ascent_method names the method; gorge edges are smoothed). The heights in a route’s geometry stay the routing graph’s node heights, for drawing, so a climb summed from them will not reproduce ascent_m.

  24. Added

    Round trips: second_pass_share

    Each loop gives second_pass_share, the share walked a second time by geometry. A loop’s status and score.clean read the larger of it and repeated_share, and strategy auto adds rings past 10 %.

  25. Fixed

    Time profile and route card climbs

    Route analysis: the last pair of time.profile now rounds to time.minutes exactly. Route card: each leg keeps its own net climb and descent, scaled to the card’s totals.

  26. Fixed

    Places in an area: the real kinds

    The reference for GET /pois/v1/bbox listed viewpoints and gave drinking_water as a kind. Viewpoints and peaks are in search and the map tiles, not here, and drinking water is the kind water. The kind parameter now lists every kind the places/1 contract defines (huts and places to stay, places to eat, transport stops, water and springs, passes, parking, villages), and the full contract has its own page.

  27. Added

    Round trips: ring strategy and loop scores

    POST /v1/roundtrips takes strategy: graph (the default, unchanged answers), ring (waypoint rings through the start, routed on the same graph) or auto (the graph first, rings when its loop is rough or missing). Each loop now says which engine made it and gives its score: length fit, clean (nothing walked twice), marked trails (null for bike) and their total. A ring loop has no quality value. Same price.

  28. Added

    Your own walking pace: the personal time model

    POST /v1/time-model/fit takes 1 to 30 of a person's own timed walks and answers their pace against the TrailSplits hike time model on level ground, uphill and downhill, each with its uncertainty, as pace_profile. Pass it to route analysis, the route brief, route weather or go windows for their own time beside the model's (time.personal, with an 80 % range). Nothing is kept: the walks are read, fitted and dropped, and the answer has no coordinates or times. A profile names its base_version; after a refit of the model it is refused (422 pace_profile_stale): fit again. 5 credits; at most 2 at a time per project.

  29. Added

    Day outings near a point

    POST /v1/outings answers "where can I walk near here?": an ordered list of day outings near a point, TrailSplits' curated outings (Switzerland and its borders so far) and round trips built from your point when they do not fill the list. Each carries its facts and why it is listed; with a date, its go window. Every rule leaves out what it cannot judge (left_out), so unknown never passes as easy. 10 credits; heavy.

  30. Added

    Time along the line in route analysis

    Route analysis now gives time.profile: cumulative moving minutes along the line, at most 500 [metres, minutes] pairs, ending at time.minutes. With a pace_profile, time.personal.profile gives the same for that person. Additive.

  31. Changed

    Search and elevation back at the plan rate; shared ceilings

    Search and elevation follow your plan's rate again (both measured above 80 requests a second). Routes, search and elevation now have a ceiling shared by all API users together: 50, 80 and 80 requests a second. Past one you get 429 rate_limit with limit "operation_total" and Retry-After. Static maps stay at 2 a second and analyses at 4 at a time per project.

  32. Added

    Bulk jobs

    POST /v1/jobs takes up to 100 items (route analysis, elevation profile, GPX clean or simplify, places along a route, pace plan), each exactly the body its own endpoint takes, and answers them in the background: the same answers, later. Poll GET /v1/jobs/{id}; read each answer at /items/{n}. 1 credit to submit, each item charged as its own call when it runs, nothing for a refused or never-started item; results kept 72 hours; 2 open jobs per project. Secret keys only.

  33. Added

    Hike times say which countries they rest on

    In route analysis and round trips, time.region gives the country holding most of the line, its share, and every country crossed with the number of its published legs in the calibration; time.notes flags thin coverage and lines mostly in Britain or Greece. A country with no published times puts the time outside_calibration with that reason. Additive; no factor is applied to the minutes.

  34. Fixed

    Route weather: sharp summits no longer shade themselves

    With sun: true, the last sharp summits that read the evening sun as hidden too early now agree with lidar (the Säntis in all 27 checks). The stated horizon angle at a sharp summit can still be a few degrees high; the state reads borderline there. No field changed.

  35. Fixed

    Climb on flat routes

    Route climb now ignores rises under 4 m on a line that stays flat (method route-smoothed-100m+flat4): extra climb on flat courses fell from about 2.8 to 0.2 m per km. The same figure is used by route analysis, elevation profiles, routes and briefs. Flat lines on the Copernicus surface model carry a new unknown, climb_low_confidence; high bridges can still add climb.

  36. Fixed

    Route weather: sun and shade on sharp summits

    With sun: true, a summit point that only its own neighbouring terrain, at most 5 m higher, would shade now reads borderline instead of shade. No field changed. Some sharp summits are still read in shade too early in the evening: see the known issue.

  37. Fixed

    Go windows: daylight past midnight

    daylight.finish_before_civil_dusk_min is now measured against the dusk of the evening the walk starts. Before, a walk that ran past midnight was read against the next day's dusk and could look as if it finished in daylight. No field changed.

  38. Added

    Exits along a route

    POST /v1/route-exits gives, every kilometre of a line, the nearest mapped public road, stop, village and hut with walking minutes on mapped paths, and the longest stretch with no way out within an hour. A mapped way out, never a safe one. 5 credits; a heavy request. Route briefs take include: ["exits"] with a no_exit_within_hour notice.

  39. Added

    Trails in an area and a relation's line in the reference

    GET /trails/v1/bbox (signed routes crossing a small box) and GET /trails/v1/relation/{osm_id} (one route's full line) are now in the OpenAPI with live checks, reference pages and Try it. Both were documented on /api before; nothing changed in how they answer.

  40. Added

    Route cards to print

    POST /v1/route-card makes a card for a line: self-contained HTML or a PDF on A4 or Letter, with the map, profile, legs, water and huts, weather only when you give a date, and a QR code to your trailsplits.com link. Nothing is stored or published. 10 credits.

  41. Added

    Downloads: offline map extracts and outdoor places packs

    GET /v1/downloads/catalog lists prebuilt regional packages; POST /v1/downloads charges a package's credits once and returns signed links valid 24 hours, which need no key and support range requests. A monthly download volume per plan applies (429 download_cap). The console shows the catalog, the month's volume and the links. Packages appear as they are built; credits and volumes are provisional.

  42. Added

    Go windows: which day and start time

    POST /v1/route-windows gives the next 1–7 days × start times for a line, each window with its forecast facts at the hour you reach each point, ordered by the preferences you give and saying why. An ordering of facts, never a safety score. 3 credits. Watches now evaluate with it.

  43. Added

    Watches and signed webhooks

    POST /v1/watches stores a route and up to 7 days; TrailSplits re-evaluates it every few hours and calls your webhook (HMAC-signed with your project's secret, retried with backoff) when the best window or a thunderstorm signal changes. The console lists watches, pauses, resumes and deletes them, rotates the signing secret (shown once) and shows a 30-day delivery log without payloads. The route is kept only while the watch exists. Events start when go windows ship.

  44. Added

    Fire hotspots in route briefs; drinking water you can plan on

    Route briefs include satellite heat detections (NASA FIRMS) within 10 km in the last 48 hours, placed along the line, with a fire_hotspots_nearby notice: heat seen from space, not a fire perimeter; none found never means no fires. Route places marks each water place drinking_water_confirmed and gives the longest stretch without confirmed drinking water; the brief notice is now no_drinking_water_km (it was no_mapped_water_km).

  45. Added

    Slope at the path (experimental)

    POST /v1/route-slopes gives the stretches of a line where the terrain model at the path is 30° or steeper, in three classes, with aspect, the distance assessed and unknown, and links to the official avalanche bulletins for the areas it touches. It is the slope at the path, not avalanche terrain or a risk; the model is about 26 m. 2 credits. Route briefs can include it with include: ["slopes"]. Hike-time answers now link to the method on the conventions page.

  46. Changed

    Lower limits on search, elevation and analyses for now

    While their capacity grows, search is limited to 2 requests a second and elevation to 5 a second (burst 10 each), per project with a key or per address without one, and route analysis and route briefs to 4 at a time per project on every plan. Over a limit: 429 rate_limit with limit "operation" and Retry-After. They rise as capacity work lands.

  47. Added

    Route brief; feels-like and thunderstorm signals

    POST /v1/route-brief gives route analysis, weather at arrival time, sun and shade, places along the route and snow evidence for one day's line in one call, each the same answer its own endpoint gives, plus fact notices placed along the line. Notices are facts, never advice or a safety score. A heavy request; 10 credits. Route weather samples and sections now carry the model's feels-like temperature, CAPE and lightning potential: model output only, and a null lightning value never means none.

  48. Added

    Places along a route; sun and shade on route weather

    POST /v1/route-places lists mapped drinking water, springs, huts, shelters and transport stops near a line, in order along it, with the longest stretch without mapped water; it says where water is mapped, never that it runs. 1 credit per started 25 km. POST /v1/route-weather takes sun: true (same credits) and adds sun and shade along the route at your arrival times plus each sample's sunrise and sunset; the state is right about 97 % of the time against lidar, and no time the sun comes or goes is given.

  49. Added

    Pace plans for a course

    POST /v1/pace-plan gives splits every kilometre or mile for one GPX or GeoJSON line, from a target time or a pace on the flat, slower where the course climbs or descends steeply. Each split ends on its mark and names its terrain. 2 credits. POST /v1/route now allows legs up to 60 km and counts waypoints and legs from 0.

  50. Added

    Route through waypoints in the /v1 style

    POST /v1/route takes 2 to 100 [lon, lat] waypoints and flat settings and answers with a GeoJSON line, its legs, climb, hike time, surfaces, SAC grades, hazards and turn-by-turn steps; errors as { error: { code, message } }. Same router and credits as POST /route/v1, which stays.

  51. Added

    Browser keys, and a daily ceiling for area lookups

    The console can issue browser keys (ts_pub_…) that work only from the web origins you list, at 2 requests a second per visitor; elsewhere they get 403 origin_not_allowed. Area lookups (outdoor places and trails in a box) now have a daily ceiling per project of three times the plan's daily average credits (3,000 on Free), then 429 bbox_daily_ceiling.

  52. Added

    GPX clean and simplify

    POST /v1/gpx/clean removes repeated and broken points (and, if asked, times and sensor data) and returns the file as the file: everything else stays byte for byte. POST /v1/gpx/simplify keeps the shape within a tolerance in metres or a point budget, protects the climb and keeps stops. 1 credit each; files up to 5 MB.

  53. Added

    Elevation profile of a line

    POST /v1/elevation-profile returns the series a chart draws (distance, height, grade and position at each point) with ascent, descent, extremes and steepest stretches read from the same series. 2 credits.

  54. Changed

    Heavy requests: a limit on how many run at once

    Round trips, route analysis and route weather now also have a per-project concurrency limit: 1 on Free and without a key (per address), 2 on Starter, 4 on Pro, 8 on Business. A request over it gets 429 concurrency_limit with Retry-After: 2. The per-second rates are unchanged.

  55. Added

    A reference page for every operation, with Try it on a map

    Sixteen operations now have their own page with curl, JavaScript and Python examples, parameters, response fields, errors and the full contract, and a Try it panel that sends the request and draws the answer on a map. The OpenAPI file covers all of them, now including search, reverse search, trails, outdoor places, static maps, map matching and snow.

  56. Changed

    Search finds misspellings

    When nothing matches exactly, place search now finds near misses and German ue/oe/ae spellings of umlauts ("Matterhon", "Mittagguepfi"). Such results carry "match": "fuzzy". Exact matches are unchanged.

  57. Added

    Free plan with commercial use, keys and usage

    Free keys from the API console: 30,000 credits a month, commercial use with attribution. Calls without a key keep working with 500 credits a day per address. Keyed answers carry X-TrailSplits-Credits-Remaining, and GET /v1/usage returns your usage per operation.

  58. Added

    Weather along a route at arrival time

    POST /v1/route-weather gives the forecast at the hour you reach each part of a line, each place at its own height, with the model named per hour.

  59. Added

    Hazards on the line

    Route analysis and round trips list hazards[]: each ford, aided passage and via ferrata, placed in metres along the line.

  60. Added

    Hourly weather values

    h=1 on the weather forecast adds hourly temperature, precipitation, rain probability, wind, gusts, wind direction and weather code per point, each hour with its model.

  61. Added

    Route analysis and round trips

    POST /v1/route-analysis analyses a GPX or GeoJSON line you already have (matched path, surfaces, tagged grades, climb, hike time, unknowns). POST /v1/roundtrips returns loops from a start point from the same engine as the TrailSplits Planner, with an honest refusal when no good loop exists.

  62. Added

    In the developer preview from the start

    These operations were in the preview before this changelog began: place and trail search (GET /search/v1/forward, GET /search/v1/reverse, GET /trails/v1/search), outdoor places in an area (GET /pois/v1/bbox), terrain heights (GET /tiles/v1/elevation/{release}/sample), snow along a route (GET /tiles/v1/snow/route-forecast), map matching with surfaces (POST /valhalla/trace_attributes), static map images (POST /static-map/render) and the Valhalla-compatible POST /route/v1. Map tiles, terrain tiles and styles, free and not counted, too.

Versions and deprecation

  • New fields, operations and data can appear at any time. Clients should ignore what they do not use.
  • A breaking change (a removed field or operation, or a changed meaning) gets a new schema version and an entry here marked "Breaking", normally 30 days before it takes effect.
  • The old behaviour keeps working until the date in that entry. Key holders are told by email when a breaking change affects an operation they use.
  • Security fixes, and changes a data source forces on us, can come sooner; the entry then says why.

See also the conventions and the API terms.