Handled Locator

Rank locations by distance from a point, the way the widget ranks them for a visitor. Also answers questions about the data when given `tag` or `q` without a point.

find_nearest_locations

Full details for one location, including hours and custom fields.

get_location

The HTML snippet that puts this locator on a website, plus the public site id it carries. Paste it where the map should appear.

get_embed_code

Spotlight rules change what a visitor sees depending on where and when they search: a banner for a region or a date range, featured locations, only certain locations, or hidden ones. Lists every rule in the order they apply (after territories), with ids. Call this before changing a rule.

list_spotlight_rules

The locator's configuration history, newest first, with what caused each version. Use it to find a version number to roll back to.

list_configuration_versions

Who OWNS an address, as distinct from who can reach it: a service radius says how far a location travels, a territory decides which dealer an enquiry belongs to. Lists every territory with its owner, rank, rules and id, the territory mode, and the published version. Nothing reaches a visitor until publish_territories.

list_territories

List the locations on this locator, newest first. Use `search` to find one by name or address before editing it.

list_locations

The tags (categories) on this locator, with how many locations carry each one. Tags are what visitors filter by on the map.

list_tags

Prepare a change to how the locator looks or behaves, WITHOUT applying it. Returns the exact list of differences. Show that list to the person and get their agreement before calling apply_configuration. Call describe_configuration first so the keys are real.

propose_configuration

Make the current territories live. Writes a new version and replaces what visitors are routed by once every file is written.

publish_territories

Restore a previous configuration version. This creates a new version rather than erasing history, so a rollback can itself be rolled back.

rollback_configuration

Put the same extra field on many locations at once: a booking button, a social link, or a labelled fact like "Parking: street only". A value that is a URL becomes a clickable button; anything else shows as plain text. NOT for tags or categories, which are a different thing entirely: use tag_locations for those. Set remove to true to take the field off instead.

set_custom_field

Choose how territories affect a visitor's results: off, preferred, exclusive or fallback. Applies to the live locator straight away.

set_territory_mode

Change how an existing tag looks on the map's filters: its filter group, chip colour and icon. Only the fields you pass are changed. Tags in the same group show as one labelled filter dropdown. Use the exact tag name. The tag must already exist; to create a tag and style it at once, use tag_locations.

set_tag_style

Turn a rule on or off without deleting it. Get the id from list_spotlight_rules.

set_spotlight_rule_enabled

Add a tag to locations, or remove it from them with action "remove". Adding creates the tag if it does not exist yet. Tags appear as filter chips that visitors use on the map. When adding, you can also pass group, color or icon to style the tag in the same call. Use this for requests like "tag these as X" or "mark these as X"; tags are not custom fields. Get location ids from list_locations first.

tag_locations

Replace a rule's name, trigger, action and dates. Send the whole rule, not only the changed part: the previous values are overwritten. Get the id from list_spotlight_rules.

update_spotlight_rule

Change one or more fields on an existing location. Only the fields you send are touched. Changing the address re-geocodes it. Pass `ids` instead of `id` to apply the same fields to many locations in one call, for example hiding a batch or setting priority across a region; address, coordinates and name stay one-at-a-time.

update_location