Figure.tilemap/pygmt.datasets.tile_map: Set User-Agent to avoid blocked access to OSM tile server

[seisman]

Not sure why it worked before, but it turns out that now we need to set "User-Agent" when requesting tiles from the OSM tile server.

This PR sets the default User-Agent to something like PyGMT/v0.19.0 (+https://www.pygmt.org) and allows custom headers.

Reference:

• https://wiki.openstreetmap.org/wiki/Blocked_tiles
• https://operations.osmfoundation.org/policies/tiles/

Closes #4815.

Preview:

• Current main: https://www.pygmt.org/dev/gallery/maps/tilemaps.html
• This PR: https://pygmt-dev--4816.org.readthedocs.build/en/4816/gallery/maps/tilemaps.html
• https://pygmt-dev--4816.org.readthedocs.build/en/4816/api/generated/pygmt.Figure.tilemap.html
• https://pygmt-dev--4816.org.readthedocs.build/en/4816/api/generated/pygmt.datasets.load_tile_map.html

[seisman]

Ping @GenericMappingTools/pygmt-maintainers for reviewing this PR.

Related but slightly off-topic:
Considering that the Figure.tilemap method is used in the PyGMT paper and it doesn't work now, I think we should make a new release, maybe v0.19.1?

[yvonnefroehlich]

Not sure why it worked before, but it turns out that now we need to set "User-Agent" when requesting tiles from the OSM tile server.

This seems to be a quite new issue: In PR #4809 merged on Sunday the tile maps gallery example looks good (https://pygmt-dev--4809.org.readthedocs.build/en/4809/gallery/maps/tilemaps.html), but in #4805 merged on Monday it fails and shows the reported issue (https://pygmt-dev--4805.org.readthedocs.build/en/4805/gallery/maps/tilemaps.html) .

$ git log
commit 1c6346bf2a55fd3db519d3ca2b066644dd6e750c (HEAD -> main, origin/main, origin/HEAD)
Author: Dongdong Tian <seisman.info@gmail.com>
Date:   Tue Aug 11 16:38:51 2026 +0800

    Update the URL links to the GMT documentation (#4814)

commit a0fd47979b1fd0c5dcea9e66f206b4a219ef3679 (gmt/url)
Author: Yvonne Fröhlich <94163266+yvonnefroehlich@users.noreply.github.com>
Date:   Mon Aug 10 11:29:55 2026 +0200

    DOC/website: Use card layout for presentations (#4805)

    Co-authored-by: Dongdong Tian <seisman.info@gmail.com>

commit 9505baa5de1dfa487dc53bc118f1a08770735fad
Author: Dongdong Tian <seisman.info@gmail.com>
Date:   Sun Aug 9 18:52:45 2026 +0800

    README: Use absolute URLs for PyGMT logos (#4809)

Looking at the wikipedia pages for openstreetmap there are quite recent updates, https://wiki.openstreetmap.org/w/index.php?title=Blocked_tiles&action=history and https://wiki.openstreetmap.org/w/index.php?title=Referer&action=history.

---

This PR sets the default User-Agent to something like PyGMT/v0.19.0 (+https://www.pygmt.org) and allows custom headers.

With the changes in this PR the tile maps gallery example seems to work again, including when building the documentation locally.

I am wondering if our weekly Link-Checks on Sundays can catch this. Maybe we should add a note to the release checklist to manually check this gallery example shortly before making a new release.

---

Related but slightly off-topic:
Considering that the Figure.tilemap method is used in the PyGMT paper and it doesn't work now, I think we should make a new release, maybe v0.19.1?

I am afraid yes. This issue affects all PyGMT versions, i.e. using a lower version does not work as an (unelegant) workaround. Thus, the Figure.tilemap method is currently not working at all, and it's likely multiple users will face this issue (so far I see no reports on the forum). It's almost one and a half months until the end of September, which is the considered time range for the release of v0.20.0.