Waypost Suite — Documentation

Guide to installing and using Waypost Suite (version 1.0.0). The Suite is standalone, so this page covers the whole plugin.

1. Installation

1. In WordPress, go to Plugins → Add New → Upload Plugin and upload waypost-suite.zip. Updates are delivered through WPBay.
2. Switch on Waypost Suite on the Plugins screen. Everything works straight away; there is nothing else to enter.
3. If the free Waypost Locator & Maps is installed, deactivate it first. The Suite uses the same tables, so your locations, categories and settings stay.

Requires WordPress 6.3+ and PHP 7.4+. There is no cap on the number of locations.

2. Adding locations

The short setup wizard (Waypost → Setup, offered until the first location exists, and again from Tools) picks a map style, the address service, a start position, your first location and a page for the locator. Every step can be skipped. To add locations by hand:

1. Open Waypost → Locations → Add location. Fill in the name and address.
2. Press Find this address on the map. The pin is placed from the address; drag it, or move it with the keyboard arrows, to fine-tune. A pin placed from only a city or postcode is marked "approximate".
3. Add phone, email, website and categories. Set the weekly opening hours, or apply an opening-hours template. Exceptions (holidays, special days) override the weekly hours for one date. The editor suggests the time zone that fits the address; it is never applied without your click.
4. Add photos, a logo and YouTube, Vimeo or video-file links on the Photos and video tab. Videos load only after the visitor presses play.
5. Set the status to Published and save. Draft, pending, temporarily closed and archived are also available; only published and temporarily closed locations are shown to visitors.
6. Add [waypost] to a page.

Unsaved changes are kept in your own browser, so they survive a closed tab. Undo last save is offered for 15 minutes, and every save is kept as a revision you can compare and restore.

3. Shortcodes, block and widgets

In the block editor, insert the Waypost locator block; it has the main options in the sidebar (the "Search this area" and layer options are set in Settings or by shortcode). With Elementor, use the Waypost Locator and Waypost Location widgets.

4. Locator map and result cards

Settings → Locator map sets the defaults for every locator: layout, height, which controls show, the "Search this area" behaviour and the layer switcher. Settings → Location cards chooses which parts a result card shows (open/closed and distance, categories, address, custom fields, phone and website, buttons) and in which order. Reorder with the arrow buttons or by dragging.

• Search this area: when the visitor drags or zooms the map, a button offers to search the visible area (or the search runs by itself with auto). Only visitor moves count, and the number of results is announced.
• Layer switcher (off by default): light or dark map from the same tile server, and pins on or off.
• Print list prints the current results.
• Searches are kept in the address (wyp-q, wyp-r, wyp-cat, wyp-open), so a result list can be shared and survives a reload.
• The layout mirrors on right-to-left sites.

5. Directions

The Directions buttons are ordinary links to OpenStreetMap, Google Maps, Apple Maps and Waze. When the visitor searched from a place, it is passed on as the starting point. Nothing is sent from your site; the visitor's browser connects only when they click.

6. Everyday tools

• Quick edit in the locations list changes the name, phone, status, categories and opening hours without opening the editor. Tick several rows to publish, unpublish, change categories, apply an hours template or delete them at once.
• Waypost → Map view shows every placed location. Draw a box or select what is in view, then use the same bulk actions. Filters show approximate pins and likely duplicates.
• Waypost → Duplicates finds pairs with similar names close together or the same address. Merging keeps the location you choose and moves categories and hours from the other.
• Tools → Opening-hours templates: five starters, plus your own (save a week from the editor).
• Tools → Move settings to another site: download the settings as JSON and load them elsewhere. Access tokens are never included.
• Every Waypost screen has help tabs (the Help button at the top right).

7. Location pages and sitemap

Every published location gets its own page at /locations/its-slug/. Change the base under Settings → General → Address of location pages; old addresses redirect (301) when a slug changes. Pages have a title, description, canonical link and social preview tags, structured data, opening hours, directions and the contact form, and are listed in the WordPress sitemap (/wp-sitemap.xml). Turn a page off per location in the editor. Themes can override the template with waypost/location.php. With plain permalinks the pages use ?wyp_location=slug.

8. Contact messages

Visitors can write to a location with the form on its page or with [waypost_contact id="12"]. Messages are stored under Waypost → Messages (statuses New, In progress, Done, Spam) and emailed with your site's mail setup to the location's email address, or to the site address. The form requires a consent tick, and is protected by a signed time token, a hidden field and a rate limit, without a third-party CAPTCHA. Messages are included in the WordPress personal-data export and erase tools.

9. Suggested locations

[waypost_submit] lets visitors suggest a location. Suggestions wait under Waypost → Suggestions; approving one publishes it, rejecting deletes it. In both cases the sender's email address and answers are deleted once you decide.

The form builder on the same screen shows, hides, requires or renames the optional fields (name, street, city and email are always asked) and adds up to five questions of your own: short or long answer, a choice list, or yes/no. Missing or invalid answers are named next to the form.

10. Insights

Waypost → Insights shows, for the last 7, 30 or 90 days: searches with and without results, the most frequent searches, searches that found nothing (where people look for you), demand by area (about 40 km cells), the most viewed locations, and clicks on directions, website and phone. Counting uses no cookies and stores no IP address or browser details; visits are estimated with a value that changes every day. Staff are not counted. Raw events are kept 90 days by default (Settings).

Each figure is compared with the previous period of the same length. A "Worth a look" box points out sudden rises in searches that found nothing and sharp drops in searches. Under Settings → Insights you can have those alerts emailed (at most once a day, off by default).

Analytics bridge (off by default): "Also send locator events to" passes searches (with the number of results) and clicks to Google Analytics 4, Matomo or Plausible. This happens only in the visitor's browser, only when that tool is already on your page, and only after the visitor gave statistics consent. Search words are never passed on.

11. Webhooks

Waypost → Webhooks: add an https address and choose events: location added, changed or moved to the trash, message received, location suggested, import finished, pickup order placed (WooCommerce). Waypost sends a JSON POST in the background and retries failed deliveries; after 10 failures in a row the webhook is paused. The last deliveries are listed with the answer code and time.

Each delivery is signed. The signing secret is shown once, when you add the webhook. Check the X-Waypost-Signature header: t=<unix time>,v1=<HMAC-SHA256 of "t.body">.

// PHP receiver
$body = file_get_contents( 'php://input' );
preg_match( '/t=(\d+),v1=([a-f0-9]{64})/', $_SERVER['HTTP_X_WAYPOST_SIGNATURE'] ?? '', $m );
$good = $m && abs( time() - (int) $m[1] ) < 300
     && hash_equals( hash_hmac( 'sha256', $m[1] . '.' . $body, WAYPOST_SECRET ), $m[2] );

12. REST API for managing locations

Manage locations from other systems with WordPress application passwords (Users → Profile → Application Passwords):

curl -u "user:application password" -H "Content-Type: application/json" \
  -d '{"title":"Leeds","address1":"1 Park Row","city":"Leeds","country_iso2":"GB","status":"draft"}' \
  https://example.com/wp-json/waypost/v1/locations

PUT and PATCH both change only the fields you send. Invalid values return 400 with a message. An OpenAPI 3.1 description of every route, method and parameter, generated from the installed build, is at /wp-json/waypost/v1/openapi.

13. Floor plans

Waypost → Floor plans: give the plan a name, add one image per level (from the media library) with a text description, and place pins by clicking the image or by typing the position. A pin has a label, an optional description and can link to a location's page. Show it with [waypost_plan id="3"], or one level with level="2". On the page, each pin is a button that opens its details with mouse or keyboard, and every level also has a numbered text list of its pins.

In the plan editor you can download the whole plan (.json) or its pins (.csv), and replace all pins from a CSV file with the columns label, level, x, y, location_id, location_external_id, description, key. The level can be a name or a number, and x/y are percentages of the image. If any row has a problem, nothing changes and the row is named. On Floor plans, Import a floor plan loads a .json file as a new plan. Level images are looked up in your media library and never downloaded, so upload them first when moving a plan between sites.

14. Look and feel

Settings → Look and feel: twelve styles (Standard, High contrast, Soft, Square, Rounded, Ocean, Forest, Sunset, Berry, Slate, Paper, Night), each checked for WCAG AA contrast. Also an accent colour (text on buttons switches between black and white for contrast, and you are warned when a colour is too light for links), corner radius, default map height and font. A live preview shows a sample locator with your choices, together with a contrast report.

15. Map, address and route providers; exports

Besides OpenStreetMap, the Suite can use OpenFreeMap, MapTiler, Stadia Maps, Mapbox and Geoapify maps, a custom tile address, the LocationIQ, OpenCage, MapTiler, Stadia, Mapbox and Geoapify address services, and OSRM, OpenRouteService or Geoapify routes. Each is off until you choose it in Settings and, where needed, enter the access token from your account with that provider; tokens are stored encrypted. With a route service selected, each result card gets a Route here button once the visitor's starting point is known: distance, time and turn-by-turn steps appear on the page and the route is drawn on the map. The directions links stay available as a fallback. Marker clustering is included. Exports: CSV, Excel (XLSX), JSON and GeoJSON.

16. Custom fields

Waypost → Custom fields: add fields such as text, long text, number, date, yes/no, a choice list or a web address. Each field can be required, searchable, and shown on cards and location pages. Choice and yes/no fields can be offered to visitors as filters. Fields are included in CSV import and export. Developers can register their own field types with the wyp_field_types filter (see docs/hooks.md).

17. WooCommerce store pickup

With WooCommerce, add the Local pickup – Waypost shipping method to a shipping zone and turn on Store pickup for the locations that offer it. Customers then pick a location at checkout (classic and block checkout). The choice is shown on the order, in the emails and in My Account. A "Ready for pickup" status sends its own email, and Waypost → Pickup orders lists the orders per location.

18. Scheduled sync from a Google Sheet or CSV

Tools → Scheduled sync from a feed: enter the address of a published Google Sheet (CSV) or any CSV file. Waypost downloads it on the schedule you choose and creates or updates locations. Unchanged files and rows are skipped, you choose how conflicts with edits made in WordPress are handled, and failures are emailed. WP-CLI: wp waypost feed-sync.

19. Multilingual locations

With Polylang, WPML or a list of languages you set yourself, each location can have its own title, description, hours note and button text per language, and can be hidden in a language. Category names and custom-field labels go through the translation plugin's string translation. Columns like title@fr work in CSV import and export.

20. Import, export and migration

Waypost → Import & Export.

• CSV import: upload a CSV (comma, semicolon or tab; UTF-8 or Windows-1252 are detected). Waypost matches your column headers to its fields and shows the mapping before anything is written. Choose create, update or create and update, and how rows are matched (your own ID column, Waypost ID, slug, or name + address).
• Dry run first: it reports what would be created, updated or skipped, row by row, without saving.
• Large files run in the background in slices; you can leave the page. Each bad row is reported on its own and does not stop the rest.
• Undo: the last import can be rolled back. Rows it created go to the trash; rows it changed get their earlier values back. Import records are kept for 30 days.
• Hours can be given as text (Mo-Fr 09:00-17:00; Sa 10:00-14:00), as JSON, or as one column per day. Categories as Parent > Child, several separated by |.
• CSV export of all locations, and a 10-row sample file showing every column.
• Migration from WP Store Locator and Agile Store Locator, when either plugin's data is present: one click copies their locations and categories into Waypost. The other plugin's data is not changed.
• Spreadsheet formulas in cells (starting with =, +, - or @) are neutralised on export.
• WP-CLI: wp waypost import file.csv --mode=upsert --match=external_id --dry-run, wp waypost export out.csv, wp waypost import-undo <batch>.

21. Address lookup and the background queue

Addresses are turned into map positions by Nominatim (OpenStreetMap) by default. Results are cached in your database, and requests are queued and spaced at one per second, as the public service requires. Typed-ahead suggestions never use the public service; they come from your own locations.

Under Settings → Address lookup you can point Waypost at your own Nominatim or Photon server. A server on your own network is only reachable after you tick allow private endpoints; otherwise private and local addresses are refused, and every request uses WordPress's safe HTTP functions.

The queue runs with WordPress cron. To run it from the system instead, turn off Run background jobs with WordPress cron and call wp waypost queue-run.

22. Consent gate and consent tools

The consent gate is on by default: no map server is contacted until the visitor presses Load map. The list and the search work before that. The visitor's choice is kept in their browser's local storage, not in a cookie.

If your site uses the WP Consent API, Complianz, Borlabs Cookie, CookieYes, Cookiebot, iubenda, Real Cookie Banner or Cookie Notice, Waypost also accepts consent given there (the category is set in Settings → Privacy and consent, default marketing). You can switch the gate off if your own setup already covers map consent.

23. Structured data for search engines

Single-location shortcodes add LocalBusiness structured data (JSON-LD) with name, address, position, phone, website and opening hours. Choose the business type (Store, Restaurant, AutoRepair and others) in Settings → Search engines, and whether to include the email address (off by default). Developers can change or remove it with the wyp_jsonld filter. When an SEO plugin is active, see Integrations.

24. Integrations

• SEO plugins: with Yoast SEO, Rank Math, All in One SEO or SEOPress active, Waypost's structured data joins that plugin's graph instead of being printed twice.
• Page caches: WP Rocket, LiteSpeed Cache, W3 Total Cache and WP Super Cache are cleared shortly after locations change (filter wyp_purge_caches_enabled to turn it off).
• Elementor: Locator and Location widgets, also working in the editor preview.
• Privacy guide: suggested text for your privacy policy appears under Settings → Privacy → Policy Guide, based on the services you selected.

25. Developers

• Public REST API under /wp-json/waypost/v1/: search (q, lat, lng, radius, cat, open_now, bbox, limit, page, sort, lang, map), suggest, locations/{id}, maps/{id} and route. Public routes are read-only and rate-limited per visitor.
• About 100 PHP hooks (prefix wyp_) and JavaScript wp.hooks filters and actions, all listed in docs/hooks.md in the plugin folder. Examples: wyp_card_parts and wyp_card_part_html to add a part to result cards, wyp_locator_before/wyp_locator_after, wyp_service_disclosure to list your own outside service in Settings, and wyp_help_tabs.
• WP-CLI: wp waypost queue-run, queue-status, cache-stats, doctor, migrate, import, export, import-undo, feed-sync. The Suite adds the REST write API above and /wp-json/waypost/v1/openapi.
• Locations live in their own database tables with a geographic index. Measured on a test server: a 25 km search over 100,000 locations takes about 2 ms (median), over 500,000 about 10 ms.

26. Accessibility

Waypost aims at WCAG 2.2 AA: every control works from the keyboard, the number of results is announced to screen readers, focus is always visible, and high-contrast and dark modes and reduced motion are respected. The list works without the map, the layout mirrors for right-to-left languages, and every admin screen has help tabs. Wherever something can be dragged, buttons or fields do the same. Please report any barrier to admin@007aj.com.

27. Privacy and personal data

• No cookies are set for visitors. The map-consent choice is kept in the browser's local storage.
• Waypost does not contact 007aj.com.
• Third parties are contacted only as listed under External services below. Settings → External services shows the same list on your site, with what each one receives and whether it is in use.
• Contact messages are personal data stored in your database; they are covered by the WordPress personal-data export and erase tools. The email and answers on a suggestion are deleted once it is approved or rejected.
• The analytics bridge (off by default) works only in the visitor’s browser, after statistics consent, and never passes on search words.
• Insights store no IP address, no browser details and no cookie.
• Webhooks send data only to addresses you add.

Privacy policy of the plugin author: https://007aj.com/privacy.

28. Reporting a security issue

Please report suspected vulnerabilities privately, not in a public forum: through Patchstack's report form (https://patchstack.com/database/report) or to the WordPress.org Plugins Team (plugins@wordpress.org). The response targets are: acknowledgement within 3 working days, a fix for a critical issue within 72 hours of confirmation, and within 14 days for a high one. SECURITY.md in the plugin folder has the full policy.

29. External services

Waypost connects to the services below. Each is used only for the purpose shown.

OpenStreetMap map tiles (tile.openstreetmap.org)

• What it is used for: the background map images.
• Data sent: the visitor's IP address and browser details (as for any image request), plus the map area being viewed (tile numbers) and the address of your page as the referrer.
• When: only after the visitor presses "Load map" (or has done so before), or immediately if you turn the consent gate off in the settings.
• Terms: https://operations.osmfoundation.org/policies/tiles/
• Privacy: https://osmfoundation.org/wiki/Privacy_Policy

Nominatim address search (nominatim.openstreetmap.org)

• What it is used for: turning a street address into a map position (geocoding) for locations you save, and, optionally, a visitor's typed place name into a search position.
• Data sent: the address or place text, your site's address and an identifying User-Agent that includes your site address and the administrator email (as the Nominatim usage policy requires), and the server's IP address.
• When: when an administrator saves a location with an address and no position, or presses the geocode button; when a visitor submits a place search (if the visitor lookup is enabled). Results are cached in your database, so the same text is not sent twice. Requests are limited to one per second. Typed-ahead suggestions never use this service.
• Terms: https://operations.osmfoundation.org/policies/nominatim/
• Privacy: https://osmfoundation.org/wiki/Privacy_Policy

Photon address search (photon.komoot.io)

• What it is used for: an alternative for the visitor place search. It is a fallback and can be turned off or replaced in Settings.
• Data sent: the place text a visitor submitted, your site's address and identifying User-Agent, and the server's IP address.
• When: when a visitor submits a place search and the local index and earlier providers produced no result, if enabled. Cached afterwards.
• Terms and fair-use notes: https://photon.komoot.io/
• Privacy: https://www.komoot.com/privacy

Directions links

The "Directions" buttons are ordinary links to openstreetmap.org, Google Maps, Apple Maps or Waze. Nothing is sent from your site; the visitor's browser connects only if they click.

Videos you add to a location (YouTube, Vimeo)

• What it is used for: playing a video you linked on a location (Photos and video tab).
• Data sent: when the visitor presses the play button, their browser loads the player from www.youtube-nocookie.com (YouTube, privacy-enhanced mode) or player.vimeo.com (with "do not track"), which receives the visitor's IP address, browser details and your page address. Nothing loads before the press; .mp4/.webm files load from the address you entered.
• YouTube terms: https://www.youtube.com/t/terms – Google privacy: https://policies.google.com/privacy
• Vimeo terms: https://vimeo.com/terms – Vimeo privacy: https://vimeo.com/privacy

You can point Waypost at your own Nominatim or Photon server in Settings; then no data goes to the public services.

Optional providers in the Suite edition

These are off until an administrator selects them in Settings. Each receives only what is needed for its job: map providers receive the visitor's IP address, browser details, the map area viewed and your page address as referrer; geocoders and routers receive the address or coordinates being looked up, your access token for that provider, and the server's IP address. Access tokens are stored encrypted in your database.

• OpenFreeMap (tiles.openfreemap.org, openfreemap.org) – vector map tiles and styles. Terms: https://openfreemap.org/tos/ – Privacy: https://openfreemap.org/privacy/
• MapTiler (api.maptiler.com) – tiles and geocoding. Terms: https://www.maptiler.com/terms/ – Privacy: https://www.maptiler.com/privacy-policy/
• Stadia Maps (tiles.stadiamaps.com, api.stadiamaps.com) – tiles and geocoding. Terms: https://stadiamaps.com/terms-of-service/ – Privacy: https://stadiamaps.com/privacy/privacy-policy/
• Mapbox (api.mapbox.com) – tiles and geocoding. Mapbox geocoding results are only shown with a Mapbox map and are not stored by Waypost. Terms: https://www.mapbox.com/legal/tos – Privacy: https://www.mapbox.com/legal/privacy
• Geoapify (maps.geoapify.com, api.geoapify.com) – tiles, geocoding and routes (Geoapify Routing uses the same access token). Terms: https://www.geoapify.com/terms-and-conditions/ – Privacy: https://www.geoapify.com/privacy-policy/
• LocationIQ (us1.locationiq.com) – geocoding. Terms: https://locationiq.com/tos – Privacy: https://locationiq.com/privacy
• OpenCage (api.opencagedata.com) – geocoding. Terms: https://opencagedata.com/terms – Privacy: https://opencagedata.com/gdpr
• OSRM public demo server (router.project-osrm.org, run by FOSSGIS) – driving routes; the demo server is for reasonable, non-commercial use (max. 1 request per second), so point Waypost at your own OSRM server for commercial sites. Usage policy: https://github.com/Project-OSRM/osrm-backend/wiki/Demo-server – Privacy: https://fossgis.de/datenschutzerkl%C3%A4rung/
• OpenRouteService (api.openrouteservice.org) – routes. Terms: https://openrouteservice.org/terms-of-service/ – Privacy: https://heigit.org/privacy-policy/
• A custom tile URL that you enter yourself.

Webhooks and email in the Suite edition

• Webhooks: when an administrator adds a webhook address under Waypost → Webhooks, Waypost sends a signed JSON POST to that address (https only) when the chosen events happen. Data sent: the event name and the changed location's public fields, or for "Message received" the location and the message fields (name, email, phone, message). Nothing is sent until you add an address, and you decide where it goes.
• Contact messages are emailed with your site's own mail setup (wp_mail) to the site or location address; no other service is involved.
• Insights (search and click counts) are stored only in your database, without cookies and without IP addresses. Optional alert emails go to the address you choose through wp_mail.
• Scheduled import (Waypost → Tools): when an administrator enters a CSV address (for example a published Google Sheet on docs.google.com), your server downloads that file on the chosen schedule. Data sent: a request for that address from your server's IP address, with Waypost's identifying User-Agent (your site address and administrator email). Nothing is fetched until you enter an address. Google terms: https://policies.google.com/terms – Google privacy: https://policies.google.com/privacy
• Analytics bridge (off by default): if Google Analytics 4, Matomo or Plausible is already on your page and the visitor gave statistics consent, Waypost passes locator events (search performed, location clicked) to that tool in the visitor's browser. Search words are never passed on. Waypost loads no analytics script and sends nothing itself; what the tool receives is covered by that tool's own terms.
• WooCommerce store pickup works inside your shop; no outside service is involved.

30. Deactivating, uninstalling and deleting data

Deactivating stops everything but keeps your data. Deleting the plugin also keeps your data unless you first turn on Settings → Uninstall → Delete all data when the plugin is deleted; then all Waypost tables, options and scheduled jobs are removed.

Support: admin@007aj.com · Privacy · Terms · 007aj.com