=== MatrixMap – Google Maps, OpenStreetMap, Store Locator & World Maps ===
Contributors: MatrixAddons
Tags: maps, google maps, openstreetmap, store locator, interactive map
Requires at least: 6.5
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 2.0.1
License: GPLv3
License URI: https://www.gnu.org/licenses/gpl-3.0.html

Maps that work without an API key: a visual map builder, a store locator with "near me" search, and clickable world and region maps.

== Description ==

**[Live demo](https://playground.wordpress.net/?blueprint-url=https://ps.w.org/geo-maps/assets/blueprints/blueprint.json) | [Website](https://matrixaddons.com/plugins/matrixmap/) | [Features](https://matrixaddons.com/plugins/matrixmap/#features) | [Free vs Pro](https://matrixaddons.com/plugins/matrixmap/#compare) | [MatrixMap Pro](https://matrixaddons.com/plugins/matrixmap/#pro) | [Pricing](https://matrixaddons.com/plugins/matrixmap/#pricing) | [FAQ](https://matrixaddons.com/plugins/matrixmap/#faq) | [Documentation](https://matrixaddons.com/plugins/matrixmap/docs/) | [Support](https://wordpress.org/support/plugin/geo-maps/)**

MatrixMap puts maps on your site in minutes, with **no API key, no account and no monthly bill**. Build a map with a visual editor, add a store locator that finds the nearest locations, or colour a world or country map with your own data. Everything is keyboard and screen reader accessible, and nothing loads until a visitor needs it. See it on the [MatrixMap website](https://matrixaddons.com/plugins/matrixmap/) or try the [live demo](https://playground.wordpress.net/?blueprint-url=https://ps.w.org/geo-maps/assets/blueprints/blueprint.json) right in your browser.

https://www.youtube.com/watch?v=v6zfepSNTt8

= Why MatrixMap? =

* **Free where others charge:** the store locator, 302 region maps (including every US county), CSV import and plugin importers are all in the free plugin, with no limits on maps, places or locations and no MatrixMap branding on your maps.
* **No API key, no billing account:** maps and address search work the moment you activate the plugin.
* **Built for real sites:** privacy-friendly loading, keyboard and screen-reader support, and a 2 KB loader that only runs on pages with a map.
* **Easy to switch:** bring your maps and stores over from eight popular map and store locator plugins without editing a page.

= Made for =

Store and dealer locators, franchises and chains, restaurants and cafés, real estate and property listings, tours and travel routes, events and venues, service areas and sales territories, and data stories such as election results, sales by state or members by country.

= Three kinds of map =

See them in action on the [MatrixMap website](https://matrixaddons.com/plugins/matrixmap/#features).


* **Maps with places.** Search for an address or click the map to drop a pin, then add a title, text, a photo, a phone number and a link. Group places into categories that visitors can filter. Draw areas, routes and circles, or add a GPX, KML or GeoJSON file.
* **Store locator.** Keep your stores, dealers or offices as locations, each with an address, contact details, opening hours and your own extra details (parking, languages, services…). Visitors search by address or postcode, with suggestions from your own locations as they type, or tap **Use my location**. They get the nearest locations with distances, "Open now" status and one-tap directions in Google Maps, Apple Maps or Waze. Add the **Store Search** box to your home page or header to send visitors straight to their results.
* **World and region maps — 302 of them, all free.** The world, continents, US states and **the counties of every US state**, the regions of 200+ countries, and detailed maps: French departments, Italian and Spanish provinces, UK local authorities, German districts, Indian districts, Australian council areas, New Zealand districts, Canadian economic regions, Philippine provinces and the municipalities of every Mexican state. Click a region on the map to edit it, edit many at once, or paste a spreadsheet to make a data map with a legend. Regions can link to pages or open their details in a panel beside the map or a pop-up window. Region maps load no map tiles and use no third-party services.
* **Region maps your way:** colour each region or colour by value, bubbles, labels, groups, lines between places, pins or dots or your own icons with names beside them, start zoomed in on the regions you choose, limit the zoom, tooltips on hover or on click, and fade or hide regions without data.

= Built around location =

* **Near me:** visitors share their location once and get the nearest results and directions from where they are.
* **Approximate location without asking:** if your site is behind Cloudflare, CloudFront, Vercel, Fastly or Akamai, the locator can start near the visitor's city using the country and city those networks already send. No prompt, no IP database, no extra service.
* **Smart address search:** results favour the country your visitor is in and the countries where you have locations, and "Did you mean…?" suggestions help with ambiguous places.
* **Fast radius search** from its own location index, even with thousands of locations.
* **Correct opening hours everywhere:** each location's time zone is worked out from where it is, so "Open now" is right for every branch.

= No API key needed =

Maps use free OpenStreetMap-based map styles (from OpenFreeMap) out of the box. You can switch to other free styles (topographic, cycling, public transport, satellite imagery), or add a key for Google Maps, MapTiler, Thunderforest or Mapbox if you prefer.

= Privacy, speed and accessibility =

* **GDPR-friendly loading:** with a consent plugin (WP Consent API, Complianz, Cookiebot, CookieYes, Borlabs, iubenda), maps wait for consent. Visitors can also load a single map with one click.
* **Nothing on pages without a map.** On pages with a map, a 2 KB loader waits until the map scrolls into view and then loads only what that map needs.
* **Accessible:** markers are real buttons, popups can be used with the keyboard, and each map comes with a text list of its places. Region maps include a data table.
* **No scroll-jacking:** on mobile the page scrolls normally and two fingers move the map; on desktop, Ctrl + scroll zooms.
* Works with WP Rocket, LiteSpeed Cache, Perfmatters, SiteGround Optimizer, Autoptimize and FlyingPress.

= Made for the block editor =

Start from a ready-made template (one location, places with a list, a route, a store locator, countries you serve, a data map) or a blank map. The Map, Store Locator, Region Map and Store Search blocks show a live preview in the editor, and you can create or edit a map without leaving the page. Shortcodes and a classic widget work too.

= Switching from another map plugin? =

MatrixMap imports your maps from **WP Go Maps**, **MapPress**, **WP Maps** and **Interactive Geo Maps (MapGeo)**, and your stores from **WP Store Locator** and **Agile Store Locator**. It can also show **Leaflet Map** shortcodes and **WP Map Block** blocks. The other plugin's data is only read, never changed. When you deactivate the old plugin, its shortcodes and blocks show the MatrixMap version, so no page needs editing.

= Also included =

* Clustering for maps with many places
* Location categories with colours, and category filter buttons
* Popup text with simple formatting (bold, italic, links, lists)
* CSV import with column matching, and CSV and GeoJSON export
* Special opening hours (holidays) and temporary closures
* Map styles, marker colours, icons and your own marker images
* Full-screen button, "show my location" button and scale bar
* Developer hooks and a REST API

= MatrixMap Pro =

Everything above is free, with no limits on maps, places or locations. **[MatrixMap Pro](https://matrixaddons.com/plugins/matrixmap/#pro)** is an optional add-on for businesses that want their maps to bring in customers. It adds:

https://www.youtube.com/watch?v=cWmUX5fn68k

**Store locator and locations**

* **[Directions on your own map](https://matrixaddons.com/plugins/matrixmap/#pro)** – driving, walking and cycling routes drawn on the map with travel time and turn-by-turn steps, from a locator result or a popup. Keyless routing (OSRM) or your own OpenRouteService, GraphHopper, Mapbox or Google key.
* **[Locator analytics and a demand map](https://matrixaddons.com/plugins/matrixmap/#pro)** – searches, directions, calls, website clicks and messages per location, and a map of where people search but you have no store. Anonymous, no cookies.
* **[A page for every location](https://matrixaddons.com/plugins/matrixmap/#pro)** – search-friendly location pages with a map, opening hours, contact buttons, LocalBusiness structured data and sitemap entries.
* **[Messages to locations](https://matrixaddons.com/plugins/matrixmap/#pro)** – a "Send a message" form in popups, results and location pages, emailed to the right store.
* **[Result templates](https://matrixaddons.com/plugins/matrixmap/#pro)** – cards, photo cards or compact rows, with Route, Message and More info buttons.
* **["Open now only" filter](https://matrixaddons.com/plugins/matrixmap/#pro)** – using each location's time zone, holidays and overnight hours.

**Growing a network**

* **[Location submissions and dealer sign-up](https://matrixaddons.com/plugins/matrixmap/#pro)** – visitors, members or dealers add their location for your review; "My locations" lets them keep it up to date.
* **[Enquiries sent to the nearest dealer](https://matrixaddons.com/plugins/matrixmap/#pro)** – a "Find a dealer" form that routes each enquiry to the closest location by email.
* **[Visitor location on any host](https://matrixaddons.com/plugins/matrixmap/#pro)** – a local copy of the free DB-IP Lite database, so the locator and blocks know the visitor's city without a third-party request.
* **[Geo-targeted content and a Nearest location block](https://matrixaddons.com/plugins/matrixmap/#pro)** – show content by country or distance, and the closest stores with distance and hours.

**Region maps and data**

* **[Click actions](https://matrixaddons.com/plugins/matrixmap/#pro)** – a region or place opens a picture gallery, a YouTube or Vimeo video, a page of your site or another web page in a lightbox.
* **[Drilldown](https://matrixaddons.com/plugins/matrixmap/#pro)** – from the world to a country's states, and on to US counties or Mexican municipalities, with an optional link to the store locator.
* **[Combined and custom maps](https://matrixaddons.com/plugins/matrixmap/#pro)** – world and North America state maps, and your own maps from SVG or GeoJSON: floor plans, campuses, sales territories.
* **[Region values from your content or a Google Sheet](https://matrixaddons.com/plugins/matrixmap/#pro)** – fill a map from categories, custom fields or a sheet or feed that refreshes in the background.

**Automation and integrations**

* **[Scheduled data sync](https://matrixaddons.com/plugins/matrixmap/#pro)** – keep locations in step with a Google Sheet, CSV or JSON feed, with preview, log and email alerts.
* **[Maps from your posts](https://matrixaddons.com/plugins/matrixmap/#pro)** – any post type with coordinates, an ACF map field or an address, plus a Posts map block for the Query Loop.
* **[Routes, tours, heatmaps and a 3D globe](https://matrixaddons.com/plugins/matrixmap/#pro)** – planned routes through your places with elevation profiles, density heatmaps and a globe view.
* **[WooCommerce "Where to buy"](https://matrixaddons.com/plugins/matrixmap/#pro)** – a store finder on product pages that lists only the stores stocking that product, with stock badges.
* **[Page builders and WP-CLI](https://matrixaddons.com/plugins/matrixmap/#pro)** – Bricks, Divi and WPBakery elements, and `wp matrixmap` commands for imports, exports and sync.
* **[Updates and email support](https://matrixaddons.com/plugins/matrixmap/#pro)** – one-click updates and email support with your licence (priority support on Agency).

Plans start at $49 a year for one site (Plus: 5 sites, Agency: 25 sites), or pay once with a lifetime licence, with a 14-day money-back guarantee. Pro installs next to the free plugin, keeps your maps as they are, and keeps working if a licence lapses; the licence brings updates and support.

**[See every Pro feature](https://matrixaddons.com/plugins/matrixmap/#pro) · [Compare Free and Pro](https://matrixaddons.com/plugins/matrixmap/#compare) · [Plans and pricing](https://matrixaddons.com/plugins/matrixmap/#pricing)** — or open **MatrixMap → Free vs Pro** in your dashboard.

= Upgrading from MatrixMaps 1.x =

Your existing maps, `[geo_maps]` shortcodes and blocks keep working exactly where they are, with the same size, markers and popups. They are converted on the fly and your old settings are never deleted.

== Installation ==

1. Go to **Plugins → Add New**, search for **MatrixMap** and install it.
2. Activate it.
3. Go to **MatrixMap → Add New Map**, or add the **Map**, **Store Locator** or **Region Map** block to any page.

For a store locator, add your stores under **MatrixMap → Locations** (or import a CSV under **MatrixMap → Import & Tools**), then add the Store Locator block or `[matrixmap_locator]`.

== Frequently Asked Questions ==

= Do I need a Google Maps API key? =

No. Maps and address search work without any key. A Google key is only needed if you want Google's own map tiles or geocoding.

= Is it GDPR compliant? =

MatrixMap stores no visitor data and sets no cookies. Map tiles come from an outside server, so by default maps wait for consent when a consent plugin is active. You can also make every map "click to load". Region maps use no outside services at all.

= How does "near me" work? =

When a visitor clicks **Use my location**, the browser asks them for permission and gives the position to the page. The page sends it to your site's own search endpoint to find the nearest locations; it is not stored and not sent to any outside service. Without a click, the locator can start near the visitor's city if your CDN provides it (see "Built around location").

= Which address search service is used? =

Nominatim (OpenStreetMap) by default, which is free and needs no key. You can switch to Photon, MapTiler or Google in **Settings**. Results are cached on your site, so each address is looked up only once.

= How many places or locations can I have? =

Up to 5,000 places per map, and thousands of store locator locations. Maps with many places cluster automatically.

= Can I show a map of only my country? =

Yes. Add a Region Map block and pick one of 302 maps: the world, continents, US states and counties, the states, provinces and regions of 200+ countries, or a detailed map (departments, provinces, districts, municipalities). You can also start the map zoomed in on the regions you choose, or hide the regions you don't use.

= Can I move maps to another site? =

Yes. MatrixMap → Import & Tools → Export downloads your maps as a file, and Import maps adds them to another site (as drafts, so you can check them first). Each map in the Maps list also has an Export link.

= Will my old maps still work after updating from 1.x? =

Yes. Nothing needs to be changed, and your 1.x data is kept.

= What is the difference between MatrixMap and MatrixMap Pro? =

The free plugin is complete: unlimited maps, the store locator, all 302 region maps, imports and exports. [MatrixMap Pro](https://matrixaddons.com/plugins/matrixmap/#pro) adds directions on your map, analytics, location pages, dealer networks, drilldown and automation. Pro installs next to the free plugin and your maps stay as they are. See **MatrixMap → Free vs Pro** in your dashboard or the [comparison on our website](https://matrixaddons.com/plugins/matrixmap/#compare) for the full list.

= Does it work with Elementor and other page builders? =

Yes. Use the MatrixMap widget in Elementor, the blocks in the block editor, or a shortcode such as `[matrixmap id="123"]` in any page builder or classic editor. MatrixMap Pro adds native Bricks, Divi and WPBakery elements.

= Can I use my Google My Maps, KML, GPX or GeoJSON files? =

Yes. In Google My Maps choose "Export to KML/KMZ" and tick "Export to a .KML file" (KMZ archives aren't supported), or use any GPX, KML or GeoJSON file, and add it to a map as a layer. Uploaded files are checked before they are accepted.

= Does it work with caching and optimisation plugins? =

Yes. With WP Rocket, LiteSpeed Cache, Perfmatters, SiteGround Optimizer, Autoptimize and FlyingPress, MatrixMap automatically excludes its small loader from their "delay", "defer" and "combine JavaScript" features, so maps don't go blank.

= Does it support multisite? =

Yes, network-wide or per site. Each site keeps its own maps, locations and settings.

= Where is the documentation? =

Online: the [MatrixMap documentation](https://matrixaddons.com/plugins/matrixmap/docs/). Inside WordPress: **MatrixMap → Docs** has a searchable guide covering setup, every feature, troubleshooting, privacy and the developer hooks. Settings screens link to the relevant page with "Learn more". For help, open a topic in the [support forum](https://wordpress.org/support/plugin/geo-maps/).

= What happens to my data if I delete the plugin? =

By default your maps, locations and settings are kept, so reinstalling brings everything back. To remove everything, turn on **Settings → Advanced → Also delete all maps, locations and settings** before deleting the plugin.

== Screenshots ==

1. The store locator: search by address or “near me”, with distances, opening hours and one-tap directions.
2. Region maps from your data: 302 ready-made maps, values pasted from a spreadsheet, a live preview.
3. Interactive data maps with tooltips, legends, zoom and an accessible data table.
4. Every US state and county — and the regions of 200+ countries — with labels and links.
5. The visual map builder: markers, shapes, styles, clustering, categories and the locator, with a live preview.
6. Add maps with the MatrixMap blocks, a shortcode or the Elementor widget.
7. Fast and mobile-friendly: maps load only where they are used and adapt to small screens.
8. Import locations from a spreadsheet (CSV), or switch from another map plugin.
9. Privacy-friendly: maps can wait for consent from your cookie plugin; no API key needed.
10. A guided dashboard with a setup checklist, health check and built-in documentation.

== External services ==

MatrixMap connects to the services below only when a map, the store locator or an address search needs them. Region maps use none of them. No data is sent until a map is shown (and, with a consent plugin, until the visitor agrees). When a map is shown, the visitor's browser downloads map images or data from the chosen provider, which receives the visitor's IP address and browser details as with any web request.

= OpenFreeMap (default map style) =
Provides the default map styles, map tiles and map fonts from tiles.openfreemap.org. Used for every map unless you choose another style. The plugin's Site Health check also requests one tile from your server to confirm the service is reachable. Service: https://openfreemap.org/ — map data © OpenStreetMap contributors.

= OpenStreetMap tile servers =
If you choose the "OpenStreetMap" style or the plugin's classic (Leaflet) engine, map images are loaded from tile.openstreetmap.org. Tile usage policy: https://operations.osmfoundation.org/policies/tiles/ — Privacy policy: https://osmfoundation.org/wiki/Privacy_Policy

= Nominatim (default address search) =
When you search an address in the map builder or location editor, or a visitor searches the store locator, the search text is sent from your server to nominatim.openstreetmap.org. Results are cached on your site. Usage policy: https://operations.osmfoundation.org/policies/nominatim/ — Privacy policy: https://osmfoundation.org/wiki/Privacy_Policy

= Photon (optional address search) =
Only if you select Photon in Settings: search text is sent from your server to photon.komoot.io. Service: https://photon.komoot.io/ — Privacy policy: https://www.komoot.com/privacy

= Optional free map styles =
Only if you select them for a map:
* OpenTopoMap (tile.opentopomap.org): https://opentopomap.org/about
* CyclOSM (tile-cyclosm.openstreetmap.fr, hosted by OpenStreetMap France): https://www.cyclosm.org/
* ÖPNVKarte (tileserver.memomaps.de): https://memomaps.de/
* Esri World Imagery (server.arcgisonline.com): Terms https://www.esri.com/en-us/legal/terms/full-master-agreement — Privacy https://www.esri.com/en-us/privacy/overview

= Google Maps Platform (optional, needs your API key) =
Only if you add a Google API key: maps that use the Google engine load the Maps JavaScript API from maps.googleapis.com, and address search can use the Google Geocoding API from your server. The "Test key" button in Settings sends one Static Maps request. Terms: https://cloud.google.com/maps-platform/terms — Privacy policy: https://policies.google.com/privacy

= MapTiler (optional, needs your API key) =
Only if you add a MapTiler key and choose a MapTiler style or MapTiler address search: maps and searches use api.maptiler.com. Terms: https://www.maptiler.com/terms/ — Privacy policy: https://www.maptiler.com/privacy-policy/

= Thunderforest (optional, needs your API key) =
Only if you add a Thunderforest key and choose its style: map images load from tile.thunderforest.com. Terms: https://www.thunderforest.com/terms/ — Privacy policy: https://www.thunderforest.com/privacy/

= Mapbox (optional, needs your access token) =
Only if you add a Mapbox token and choose its style: map images load from api.mapbox.com. Terms: https://www.mapbox.com/legal/tos — Privacy policy: https://www.mapbox.com/legal/privacy

= Directions links =
"Directions" buttons are plain links to Google Maps (www.google.com/maps), Apple Maps (maps.apple.com) or Waze (waze.com) with the destination's coordinates. Nothing is sent unless the visitor clicks one.

== Source code ==

The readable JavaScript and SCSS source is in `assets/src` and is built with `@wordpress/scripts` (`npm install && npm run build`). The development repository is https://github.com/matrixaddons/geo-maps

Bundled libraries: MapLibre GL JS (BSD-3-Clause), Leaflet (BSD-2-Clause), Supercluster (ISC), d3-geo (ISC), @tmcw/togeojson (BSD-2-Clause) and Lucide icons (ISC). Region maps are built from Natural Earth data (public domain) and US Census county boundaries (public domain, via us-atlas, ISC). Detailed maps use open government data via geoBoundaries: Survey Department of Nepal / OCHA (CC BY 3.0 IGO), UK Office for National Statistics (Open Government Licence v3.0), © GeoBasis-DE / BKG (dl-de/by-2-0), Statistics Canada (Open Government Licence – Canada), Australian Bureau of Statistics (CC BY 4.0), Stats NZ (CC BY 4.0), World Bank / INEGI (CC BY 4.0) and lgdirectory.gov.in (ODbL). See `assets/regions/LICENSE-DATA.txt`.

== Changelog ==

= 2.0.1 =
* Improved: the built-in help, settings texts and readme match the plugin (category filter buttons, supported consent plugins including iubenda, 200+ country maps, how "near me" search works).
* New: a link to the online documentation on the Docs screen, and videos of MatrixMap and MatrixMap Pro in the readme.

= 2.0.0 =
MatrixMaps is now **MatrixMap**, rebuilt from the ground up. All 1.x maps, shortcodes and blocks keep working.

**Maps and the builder**

* New: a visual map builder with a live preview (desktop, tablet, phone): address search, click-to-add, drag to move, categories, clustering, shapes and GPX/KML/GeoJSON layers.
* New: maps without an API key (OpenFreeMap vector maps), with optional Google Maps, MapTiler, Thunderforest and Mapbox.
* New: starter templates, a full-screen editor, and export/import of maps between sites.

**Store locator**

* New: search by address or "Use my location", radius and category filters, "Open now" badges, suggestions from your own locations and directions links.
* New: locations with opening hours, special hours, temporary closures, time zones and extra details; CSV import (thousands of rows, addresses placed for you) and CSV/GeoJSON export.
* New: a Store Search block that sends visitors to your locator page.

**Region maps**

* New: 302 ready-made maps — the world, continents, US states and every US county, the regions of 200+ countries, and detailed maps (departments, provinces, districts, Mexican municipalities).
* New: colour regions from your data, bubbles, legends, labels, region groups, markers, lines, a region finder, tooltips, details panels, deep links (?mm_region=) and an accessible data table.

**Everywhere**

* New: Map, Store Locator, Region Map and Store Search blocks, shortcodes and an Elementor widget.
* New: one MatrixMap admin — a Dashboard with a setup checklist and health check, Settings with search, Import & Tools, and built-in documentation (MatrixMap → Docs).
* New: switch from WP Go Maps, MapPress, WP Maps, Interactive Geo Maps (MapGeo), WP Store Locator, Agile Store Locator, Leaflet Map and WP Map Block.
* New: privacy-friendly loading — maps can wait for consent (WP Consent API, Complianz, Cookiebot, CookieYes, Borlabs, iubenda); nothing loads on pages without a map.
* Accessibility: keyboard-operable maps, regions and popups, text alternatives and screen-reader announcements.
* Performance: large location sets load a compact index and details on demand; locators download only search results; caches rebuild in the background.
* Security: hardened uploads, rate limits that can't be bypassed with spoofed IP headers, API keys only sent to pages that need them, and private data kept out of public endpoints.
* Changed: requires WordPress 6.5 and PHP 7.4.

= 1.2.2 - 2026-02-25 =
* Fixed: removed "Plugin" from the plugin name to comply with WordPress.org guidelines.
* Fixed: license mismatch between readme.txt and plugin headers (now both GPLv3).
* Fixed: added ArcGIS World Imagery service documentation.
* Fixed: output escaping throughout.

= 1.2.1 - 2026-02-25 =
* Fixed: the src directory was excluded from the package.

= 1.2 - 2026-02-25 =
* Rebranded to MatrixMaps; WordPress.org guideline, security and translation fixes.

= 1.1 - 2024-07-04 =
* Added: draw lines between markers.
* Fixed: WordPress 6.6 compatibility.

= 1.0 - 2022-03-26 =
* Initial release.

== Upgrade Notice ==

= 2.0.0 =
MatrixMaps becomes MatrixMap: a new map builder, a store locator and region maps, with no API key needed. Your existing maps keep working. Requires WordPress 6.5 and PHP 7.4.
