How it works

Maps Locator makes your entries searchable by location, for example for a store locator. It is an extension of the Maps module: Maps does all the geocoding (turning an address into a coordinate and back). A location can come from two kinds of fields:

• the Maps Locator Fieldtype (included): one address and/or latlng per entry, see Fieldtype template tag.
• the Maps Fieldtype (documentation): every marker in the field becomes a location, so an entry can have more than one location.

Maps Locator keeps its own list of locations (CP → Locations). The search tags only search that list, not the entries themselves, so an entry can only be found when it has a location in that list.

Which field to use

	Maps Locator field	Maps field in Single location mode
Input	Separate address and coordinate inputs	A search with suggestions and a draggable marker
Map in the entry form	No	Yes
Use it for	Existing sites, or when you don't want a map in the entry form	New sites

A marker of a Maps field is saved as a coordinate. Its address is only in the search index after it is looked up, see Reverse geocoding. Until then a radius search finds the location, but a locality, sub_locality or admin_level search doesn't.

When locations are indexed

• Saving an entry with a Maps Locator field: the location of that field is replaced by a new one.
  • When the field has a valid latitude and longitude (like 52.37 and 4.89, latitude -90 to 90, longitude -180 to 180), that coordinate is used and the address fields are ignored. See Reverse geocoding.
  • Otherwise the address is looked up. When the address can't be found, no location is saved, so the entry can't be found in a search.
• Saving an entry with a Maps Fieldtype field: every marker is saved as a location. Polygons, lines and other shapes are ignored. A Maps Fieldtype inside a Grid is indexed per Grid row (requires Maps 5.0.0+); deleting a Grid row removes its locations. A Maps field inside a Fluid field is indexed per Fluid item (requires Maps 5.0.0+); removing the item removes its locations.
• On every save, the entry status, title and dates are stored with the location, so searches can filter on them.
• Deleting an entry: the locations of the entry are removed.
• Reindex All (CP → Locations): rebuilds the locations of all entries, entry by entry, and removes the locations of entries that no longer have one. Reindex missing entries only adds the missing locations and looks up the ones without an address.
• Remove all locations / the remove button per row: removes locations; they come back on the next entry save or reindex.

Reverse geocoding

Reverse geocoding means looking up the address of a latlng coordinate. Maps Locator needs that address (city, street, country, ...) for the address variables in the results and for the locality, sub_locality and admin_level search types.

• Reverse Geocode latlng enabled (see CP overview): every latlng location is looked up when the entry is saved or reindexed. This is slower and uses more of your geocoding quota.
• Disabled (default): the coordinate is saved as is. The address is looked up later, by the warmup cache. Until then the address variables of that location are empty in the results.

The address that is found is usually not exactly on the entered coordinate, and the saved coordinate is then replaced by the coordinate of that address. So a location can move slightly. This happens with the setting enabled or disabled, as soon as the address is looked up.

Geocoding and caching

• All geocoding (addresses, coordinates and the location a visitor searches for) is done by Maps, with the providers enabled in the Maps CP (OpenStreetMap, Google Maps or Bing Maps). See Maps: geocoding and caching.
• Results are cached by Maps, so the same address is not looked up again until the Maps cache time has passed. Lookups that failed are tried again every time.
• Geocoding errors (no result, invalid API key, quota reached) are logged in the Maps log, not in the Maps Locator log.

Warmup cache

The warmup-cache URL (see CP overview) is meant for a cron job. Each run looks up the address of a number of locations that don't have one yet (Warmup Cache Count, default 10). A location for which no address can be found is skipped from then on.

How a search works

1. The visitor fills in the search_form and submits it.
2. The search is saved and the visitor is sent to the result_url with a unique search ID added to the URL. A saved search is kept for 2 hours; after that the result link no longer works.
3. The search_result tag reads that search ID (from the search_id parameter or the first segment after the template) and looks up the coordinate of the searched location. Without a search ID it only shows results with default:show_all="yes".
4. Depending on the search type:
   • radius: all locations within the radius are returned, sorted by distance. The distance is available as {radius}.
   • locality, sub_locality, admin_level: locations in the same city, city district or region (e.g. state/province) are returned, without distance or sorting.
5. Only locations of the given channels and with an entry status from the status parameter (default open) are returned. When categories are selected, a location must have all of them, or one of them with category_match="any" on the search_result tag. The categories are read from the entry itself, so a change of the categories counts right away.
6. Every location is one result. An entry with more locations (e.g. several markers) shows up more than once.

current_search_location shows the data of the location the visitor searched for.

The other tags

• radius: a radius search on a location you set in the tag, over all channels of the current site, with status open and without categories. It does not look up missing address data.
• query: lists locations that match the values you give, without geocoding; status open and at most 50 by default.
• Fieldtype tag: the address parts are what was entered in the field; lat/lng come from the location list, so they can differ from what was entered, or be empty when no location was saved.

How it depends on Maps

• Maps must be installed; its providers, API keys and cache are used for all geocoding. A wrong or missing provider setup in Maps means no locations and no search results.
• To show the results on a map, use the Maps tags ({exp:reinos_maps:map} with {maps:add_marker}), see the examples.
• The Maps Fieldtype is optional; when it is installed, its markers are indexed automatically. A reindex reads Maps Fieldtype fields that are channel fields, Grid columns or items in a Fluid field (requires Maps 5.0.0+), not a Maps field in Bloqs.

CP settings

See CP overview. In short:

• Reverse Geocode latlng: look up the address of latlng locations on save/reindex instead of later, see Reverse geocoding.
• Warmup cache URL / Warmup Cache Count: see Warmup cache.
• What to log: only affects the Maps Locator log, which has few messages. For geocoding problems check the Maps log.

Limitations

Every address is looked up by an external service, which has usage limits (e.g. Google's quota, or the fair use policy of OpenStreetMap). With many locations (e.g. an import, or a reindex of 100+ entries) not all locations may be geocoded, or the reindex may time out. A reindex that times out leaves the entries it didn't reach as they were; run Reindex missing entries to finish it. Keep Reverse Geocode latlng disabled for large sets and let the warmup cache fill in the addresses.

Common pitfalls

• No results at all: no channel on search_form (or default:channel), a wrong channel short name, the searched location can't be found (check the Maps log and providers), or the entries have another status than open.
• The result page shows nothing after submitting: the search ID is not the first segment after the template (set search_id="{segment_3}" or similar), or the result link is older than 2 hours.
• An entry is missing in the Locations overview: its address could not be found (check the Maps log), it was saved before the add-on was installed, or it uses a Maps Fieldtype inside a Grid and was saved before the update to 4.0.0. Use Reindex All.
• Deleted entries still show up: they were deleted before version 4.0.0, run Reindex All once. See When locations are indexed.
• locality/admin_level search finds nothing: these search types need the address of the location, which a latlng location only gets after it is reverse geocoded (setting enabled, or the warmup cache).
• Coordinates moved slightly: reverse geocoding replaced them with the coordinate of the found address.
• Empty address variables in the results: latlng locations without an address yet; run the warmup cache via cron (or enable Reverse Geocode latlng).
• Expired or future entries are found: only the entry status is checked, not the entry or expiration date. Check the entry with {exp:channel:entries} in the result loop if needed.