What is a GPX file?
GPX (GPS Exchange Format) is a standard file format for GPS data. Most hiking apps, fitness trackers, and GPS devices can export GPX files.
Where do I get GPX files?
You can export GPX files from: * Hiking apps (Gaia GPS, AllTrails, etc.) * Fitness apps (Strava, Garmin Connect, etc.) * GPS devices (Garmin, Suunto, etc.) * Google Maps (via Google My Maps)
Can I use multiple GPX files in one post?
Not currently. Only the first Map GPX block per post is used.
How do I get coordinates for markers?
Import from GPX — if your GPX file has named waypoints, click “Import as Map Markers” in the Map GPX block to create markers automatically Use the built-in address search (type any place name) Paste coordinates from Google Maps (right-click a location) Use coordinates from your GPS device or app
Can I import waypoints from my GPX file?
Yes, if your GPX file contains named waypoints ( <wpt> elements with a <name> tag). After uploading your GPX file, the Map GPX block will show an “Import as Map Markers” button with a count of available waypoints. Clicking it creates Map Marker blocks for all waypoints not already present in the post, inserted immediately after the Map GPX block. Re-clicking is safe — already-imported waypoints are detected by coordinates and skipped.
Does it work with my theme?
Mapthread is designed for block themes. It has not been tested with classic themes.
Is there a file size limit for GPX?
We recommend GPX files under 10MB. Larger files will show a warning and may be slow to render.
Can I customize the map/track/marker colors?
Not currently. But you can set emojis for each Marker instead of the default.
How do I add more map styles?
Go to Settings > Mapthread and enter your API key for any supported provider (Mapbox, Thunderforest, JawgMaps, Stadia Maps). Then select which styles to enable. Each provider offers free tiers suitable for most blogs.
Are API keys secure?
The tile provider API keys used by Mapthread are publishable tokens designed for client-side use. Security is handled via domain restrictions configured in each provider’s dashboard.
Does this work offline?
No, Mapthread requires an internet connection to load map tiles.
Where can I get support?
Post in the plugin support forum or open an issue on GitHub
Can I contribute to the plugin?
Yes! Mapthread is open source — contributions are welcome at github.com/randomwire/Mapthread
What third-party libraries does Mapthread use?
Leaflet.js (BSD-2-Clause) — Interactive map rendering Leaflet.fullscreen (MIT) — Fullscreen map control Chart.js (MIT) — Elevation profile visualization
Does Mapthread connect to any external services?
Yes. Mapthread connects to third-party services to display map tiles, geocode addresses, and look up elevation data. Below is a full description of each service, what data is sent, and when.
OpenStreetMap Tile Service Used for: Rendering the default “Street” map layer. When: Every time a visitor views a page containing a Mapthread map, the browser requests tile images from OpenStreetMap servers. Data sent: Tile coordinate requests (zoom level, x/y tile numbers) indicating the geographic area being viewed. The visitor’s IP address is visible to OpenStreetMap servers. Terms of Use | Privacy Policy | Tile Usage Policy
Esri / ArcGIS World Imagery Used for: Rendering the optional “Satellite” map layer. When: Only when the Satellite layer is enabled in Settings > Mapthread and a visitor selects it. No requests are made if the layer is disabled. Data sent: Tile coordinate requests and the visitor’s IP address. Terms of Use | Privacy Policy
OpenTopoMap Used for: Rendering the optional “Topographic” map layer. When: Only when the Topographic layer is enabled in Settings > Mapthread and a visitor selects it. Data sent: Tile coordinate requests and the visitor’s IP address. Terms of Use / Privacy Policy
Nominatim (OpenStreetMap Geocoding) Used for: Address search autocomplete when editing a Map Marker block. When: Only in the WordPress block editor when an author types into the address search field. Not triggered on the public frontend. Data sent: The search query text (partial address or place name) and the editor’s IP address. Usage Policy | Privacy Policy
Open-Elevation API Used for: Looking up elevation data for GPX tracks that lack elevation information. When: Server-side only — when a GPX file is uploaded that has no elevation data and the elevation profile feature is enabled. The request is made from the WordPress server to api.open-elevation.com , not from the visitor’s browser. Data sent: GPS coordinates (latitude/longitude pairs) sampled from the GPX track, sent from the WordPress server’s IP address. No user accounts or personal data involved. Service | Source | License (GPL-2.0)
Optional Tile Providers (each requires an API key configured in Settings > Mapthread)
The following services are only contacted when a site administrator has entered an API key and a visitor selects the corresponding map layer. In each case the browser sends tile coordinate requests, the configured API key/token, and the visitor’s IP address.
- Mapbox | Terms | Privacy
- Thunderforest | Terms | Privacy
- JawgMaps | Terms | Privacy
- Stadia Maps | Terms | Privacy
Where can I find the source code?
The compiled JavaScript and CSS files in the build/ directory are generated from human-readable source files. The full source code is available at github.com/randomwire/Mapthread
To build from source: 1. Clone the repository 2. Run npm install 3. Run npm run build
This uses @wordpress/scripts (webpack) to compile the source files in assets/js/ and assets/css/ into the production build/ directory.
