Include OSM planet file timestamp and seqno in changeset

[jake-low]

It'd be nice if the TileJSON endpoint included information about when the tileset was built (specifically the timestamp of the OSM planet file that was used). Applications might wish to display this in their UI.

Planetiler already includes this metadata when it writes a PMTiles file, for example:

$ pmtiles show example.pmtiles
pmtiles spec version: 3
tile type: mvt
bounds: (long: -180.000000, lat: -85.051129) (long: 180.000000, lat: 85.051129)
min zoom: 0
max zoom: 15
center: (long: 0.000000, lat: 0.000000)
center zoom: 0
addressed tiles count: 1084207711
tile entries count: 146457128
tile contents count: 136425150
clustered: true
internal compression: gzip
tile compression: gzip
planetiler:githash 855fa914faef8e4046c9b704401a64bc5fe83ded
planetiler:osm:osmosisreplicationseq 0
planetiler:osm:osmosisreplicationtime 2025-09-01T00:00:02Z
planetiler:buildtime 2025-06-19T14:30:46.214Z
planetiler:osm:osmosisreplicationurl
planetiler:version 0.9.1

And I think the PMTiles JavaScript implementation can read these custom metadata fields too. So I think all we'd have to do is augment the TileJSON generated by pmtiles.getTileJson() with those custom properties.

[jake-low]

Calling await pmtiles.getMetadata() in the worker's handleTilesetRequest() function returns an object containing these custom properties (plus vector_layers, which should be omitted since it's already included in the TileJSON).

So the only thing we have to do is decide how to encode the properties in the TileJSON. The simplest option is probably to put it verbatim in a metadata nested object:

{
  "tilejson": "3.0.0",
  "metadata": {
    "planetiler:githash": "855fa914faef8e4046c9b704401a64bc5fe83ded",
    "planetiler:osm:osmosisreplicationseq": "0",
    "planetiler:osm:osmosisreplicationtime": "2025-09-01T00:00:02Z",
    "planetiler:buildtime": "2025-06-19T14:30:46.214Z",
    "planetiler:osm:osmosisreplicationurl": "",
    "planetiler:version": "0.9.1",
  }
}

But a drawback of this approach is that doing this leaks implementation details about the build pipeline that could change in the future.

Another alternative would be to define some generic fields and map Planetiler's metadata there, e.g.:

{
  "tilejson": "3.0.0",
  "metadata": {
    "generator": "planetiler v0.9.1",
    "build_timestamp": "2025-06-19T14:30:46.214Z",
    "osm_timestamp": "2025-09-01T00:00:02Z",
    "osm_seqno": 0,
  }
}

Not sure exactly how best to name these fields, but the advantage is we could keep the names the same (and avoid breaking downstream code that uses them) even if implementation details change.

[1ec5]

Of these fields, the OSM timestamp would be most interesting to an application. For example, OSM Americana would display this timestamp somewhere in the corner. The generator could be interesting too for debugging purposes.