=== Pinpoint Customer Map for WooCommerce ===
Contributors: keyserintelligence, kevkeyser
Tags: woocommerce, customers, map, geocoding, orders
Requires at least: 6.2
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

See your WooCommerce customers on a map. One-click geocoding of your order history, no API key, no setup.

== Description ==

**Where are your customers?**

Pinpoint Customer Map for WooCommerce turns your order history into an interactive map, right inside your dashboard. Spot the cities where your buyers cluster, plan pop-ups and local campaigns, and finally *see* your store's reach.

This plugin was born in a real store: a family skincare business whose owner asked, "Can I see my customers on a map so I can plan in-person visits to the right cities?" This is that tool, polished for every WooCommerce store.

= Free features =

* **Interactive customer map**, OpenStreetMap with smart marker clustering, right in wp-admin
* **One-click geocoding** of your entire order history, no API key required
* **Automatic geocoding of new orders** as they arrive
* **Filters**: state/region and order status
* **Pin details**: city, order total, and a direct link to the order
* **Smart caching**, every address is geocoded exactly once, ever
* **Privacy mode**, show pins at city level instead of exact street
* **HPOS compatible** (High-Performance Order Storage)
* No data leaves your site except the address sent for geocoding (see External Services below)

= Pro =

* **Hosted high-speed geocoding**, your full order history mapped in minutes, no rate limits, no API key, no reliance on free public services
* **Business filters**, by product, order value, repeat vs first-time customers
* **Radius select + export**, draw a circle on the map, export those customers to CSV or your email tool
* Priority support

[Learn more about Pro →](https://keyserintelligence.com/pinpoint-customer-map/)

= Is the whole store mapped, or just part of it? =

The whole store. The free version maps your entire order history in the background. It uses the OpenStreetMap Foundation's public Nominatim geocoding service, generously offered under a fair-use policy of one request per second, and we respect that strictly, so a large store is mapped gradually (roughly 17 minutes per 1,000 new addresses), with every result permanently cached so no address is ever looked up twice. Pro uses a dedicated hosted geocoding pipeline that maps your entire history in minutes, with no rate limit.

== External Services ==

This plugin connects to the following external services. No connection is made until you activate geocoding.

**1. Nominatim geocoding (OpenStreetMap Foundation)**

* Purpose: converting order addresses into map coordinates.
* Data sent: the order's shipping or billing address only (you can restrict this to city + postcode in Settings). No customer names, emails, phone numbers, or order contents are ever sent. As required by the Nominatim usage policy, each request also carries an identifying User-Agent containing a static plugin identifier and a fixed developer contact email; your site URL and your store's admin email are never sent.
* When: when you start a backfill, and when a new order is geocoded.
* Usage policy: https://operations.osmfoundation.org/policies/nominatim/
* Privacy policy: https://wiki.osmfoundation.org/wiki/Privacy_Policy

**2. OpenStreetMap tile servers**

* Purpose: displaying the map background.
* Data sent: your browser's IP address and map tile requests, only when an administrator views the map page in wp-admin. Store visitors never load these tiles.
* Usage policy: https://operations.osmfoundation.org/policies/tiles/

Geocoded coordinates are stored in your own WordPress database and can be fully deleted on uninstall via Settings.

== Installation ==

1. Install via Plugins → Add New, or upload the zip.
2. Activate, then go to WooCommerce → Customer Map.
3. Click **Geocode my orders**. Your whole store is mapped in the background at about one address per second (roughly 17 minutes per 1,000 new addresses), grab a coffee.
4. Watch your customer map fill in. New orders are added automatically from now on.

== Frequently Asked Questions ==

= Do I need a Google Maps API key? =

No. The free version needs zero configuration and zero API keys.

= Is my customer data sent anywhere? =

Only the address string is sent to the geocoding service, as disclosed above, never names, emails, or order contents. The resulting coordinates live in your own database.

= Does it map my whole store? =

Yes. The free version maps your entire order history in the background. Because it uses the free public geocoding service (one request per second), a very large store can take a while on the first run, though results are cached so it only happens once. Pro uses a dedicated hosted pipeline that does the same job in minutes.

= Will this slow down my store? =

No. Geocoding runs in the background via Action Scheduler, and the map only loads inside wp-admin. Your storefront is untouched.

= Is it HPOS compatible? =

Yes, fully compatible with WooCommerce High-Performance Order Storage.

= GDPR? =

You control precision (street vs city-level), only the address is transmitted (disclosed above), and all stored geodata can be deleted on uninstall.

== Screenshots ==

1. Your customers on the map, clustered pins across the country
2. One-click geocoding with a live progress bar
3. Pin details: city, order total, and a direct link to the order
4. Free filters: narrow the map by state/region and order status
5. A preview of Pro filters, product, order value, radius select + export (upgrade to unlock)
6. Settings: address source, privacy precision, and data cleanup

== Changelog ==

= 1.0.0 =
* Initial release: customer map, whole-store geocoding backfill, auto-geocoding of new orders, state/status filters, privacy mode, HPOS support.

== Upgrade Notice ==

= 1.0.0 =
First release.
