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.

[weiji14]

Hmm, I've scanned through contextily's code/issues and found geopandas/contextily#75, and it seems they should have set a user-agent header of some sort already since 2019? Maybe the contextily- header is getting rate-limited 😅 so ok to set a custom PyGMT one, but I hope this doesn't get rate-limited too (if so, we'll know PyGMT's fig.tilemap is getting used a lot 😆).

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.

It's only not working for OpenStreetMap tiles, but should be ok for other tilemap providers. That said, yeah a v0.19.1 would probably be good in this case.

[weiji14]

Need to bump to contextily>=1.7 in pyproject.toml, ref geopandas/contextily#266 and https://github.com/geopandas/contextily/releases/tag/v1.7.0

[weiji14]

Actually, should we append a unique uuid also similar to what contextily did in geopandas/contextily@f58cb55?