This article will guide you through the process of setting up Find Your Nearest (FYN) for your organisation so you can begin getting results via the API.
You will need to be an Organisation Administrator and have FYN added to your subscription to do this.
Required time: 10 minutes
There are three steps to setting up FYN before any API calls will return results.
- Set up the rules for your organisation
- Add a custom field to return identifying values for records
- Set records to be included in results
Let's look at each of those in more detail.
Setting up the rules for your organisation
FYN uses rulesets containing one or more rules to specify which records are returned when making calls via the API, and you can have as many rulesets as needed to meet the requirements of multiple brands/integrations within your organisation.
Creating a new ruleset
From the Organisation Administration's Home page
- Select Find Your Nearest from the navigation menu, and then
- Click Create new ruleset near the top of the content page.
To get started with FYN, you're going to need a ruleset. Let's create one now.
Give your ruleset a name and select the maximum number of results you'd like FYN to return.
You can return a maximum of 255 results, but less is more when it comes to response times and user experience!
Click Continue to move on.
Creating a rule
This page of the wizard shows you the rules created for this ruleset. At the moment, you won't have any, so click New rule to start the process.
When you've created your rule, you'll be returned here and see it in the rules table.
Start by selecting the required rule type. Below, we've summarised their meanings.
Compatible with area layers only.
Uses the allocation of areas in a base layer to determine which area in a results layer should be returned.
This type is especially useful with Postcode/ZIP code geography when these have been used to define exclusivity to an area.
Compatible with area and location layers.
Uses straight-line distances to calculate the nearest records from the enquiry point.
For area records, this is the nearest boundary line. If the enquiry point is within the area, then the distance is assumed to be zero.
Creating each rule is simple enough. The magic is in how they all work together to generate the right result!
Complete your settings, and click Save and close to add the rule to the rules table.
We've gone and repeated the process of creating a rule two more times to add all of our rules.
Repeat for each rule you need, then click Continue to move on.
Saving the ruleset
The final stage simply confirms your choices through this process. If you've made a mistake, now is the time to go back and correct it.
Most processes in Vision end with a confirmation of your changes, allowing you to correct any mistakes before saving.
Take note of the layer(s) that you used for results in your rules. You will need these when setting records to be included in results.
Click Save and close to complete the process. Once saved, you may also want to note the auto-generated API key as your developers will need it.
Adding a custom field to return identifying values for records
Next, we need to create a custom field to hold the identifying information that we return each time a record is selected as a result.
You can follow the steps here to create the custom field. Make sure to set the following settings:
|Type||FYN return value|
|Layers||The layers selected when setting up your rules.|
Once complete, take note of the auto-generated API key for your new custom field as your developers will need it.
Set records to be included in results
By default, all records are excluded from being used for FYN results until they are explicitly included. Therefore, the final piece of the puzzle is to set some records to be included in the results and make sure they have a response value so they can be identified.
Including the record in FYN results
We do this from the map.
- Turn on the appropriate layer
- Click on the area/location you want to include
- Click Actions
- Click Manage FYN settings from the Find your nearest header
Once you've clicked Actions, you'll see Manage FYN settings in the actions menu.
Set your FYN settings for the record appropriately, making sure to include it in at least one rule in your ruleset (normally, you'd include it in them all). If you have more than one ruleset, make sure you're setting up the right rules.
Click Save changes.
Setting the response value
Assuming you're continuing from the previous section (if not, follow steps 1 to 2 above):
- Click Actions
- Click View/Edit information at the top of the actions menu
Enter a value that allows the system using the API to identify this record in your database. Usually, this will be a unique id/key from that system.
When done, press Save changes to complete the process.
That's it! Once your developers have integrated with the FYN API, they'll begin receiving results.