About Proximity Search

With Proximity Search, you can find the Resources closest to your Project site. When you enable it, the Resource Plan offers a Distance filter as you assign a Resource Request, so you can narrow the candidates to those within a given distance of the Phase you are staffing.

Precursive calculates that distance from the geographic coordinates of two records:

• The Phase address. Precursive geocodes the address on the Phase record you are staffing.
• The Resource address. Precursive geocodes the address on each Resource record.

Precursive converts both addresses into coordinates through the Google Geocoding API, so the feature requires a Google API key. Google charges for this service. To review the current rates, see Geocoding API Usage and Billing.

An API key is a unique identifier that authenticates the requests Precursive sends to Google. Google bills the key owner for those requests.

Before you begin

You need the following before you start:

• Salesforce administrator permissions. You edit Remote Site Settings, Custom Settings, and page layouts, so you need the Customize Application and Modify All Data permissions.
• A Google Cloud account. You create the project, enable billing, and generate the key in Step 1 below.

Set up your Google API key

Google owns the Google Cloud Console and changes its screens from time to time, so this section points you to the Google instructions rather than repeating them.

Step 1: Create the key in Google Cloud

Follow all three steps of Getting Started with Google Maps Platform. When Google asks you to name the project, Precursive suggests Precursive Proximity Search, so that you can identify the charges later.

When you finish, you have the following:

• A Google Cloud project. The project holds the key and receives the charges.
• An active billing account on that project. Google rejects Geocoding requests from a project without one.
• The Geocoding API enabled. Precursive calls this API only, so you do not need to enable any other.
• An API key. Copy it. You paste it into Salesforce later in this article.

Step 2: Restrict the key

Google asks you to choose the APIs a key can call, and may do so while you create it. Open the key on the Credentials page, then set the restrictions as follows:

1. Under API restrictions, select Restrict key, then select Geocoding API.
2. Under Application restrictions, select None. Precursive calls Google from Salesforce servers rather than from the browser, so a Websites restriction blocks every request. An IP addresses restriction works only if you maintain the full list of Salesforce outbound IP ranges for your instance, and Salesforce changes those ranges.
3. Select Save.

For the wider Google guidance on key security, see Restrict Your API Keys.

Enable Proximity Search in your Salesforce instance

You enable the feature in two steps: you allow Salesforce to call Google, then you store the key.

Step 1: Add the Remote Site Setting

Salesforce blocks outbound calls to any address that an administrator has not registered, so you register the Google endpoint first.

1. Go to Setup > Quick Find > Remote Site Settings.
2. Select New Remote Site.

3. In Remote Site Name, enter Geocode.
4. In Remote Site URL, enter https://maps.googleapis.com.
5. Leave Active selected, then select Save.

Step 2: Add your API key to Precursive Global Settings

1. Go to Setup > Quick Find > Custom Settings.
2. In the list of custom settings, select Manage next to Precursive Global Settings.

3. Select Edit next to the record named Global.
4. In Google API Key (preempt__googleAPIKey__c), paste the key you copied from Google.

5. Select Save.

Precursive now offers the Distance filter on the Resource Plan, and geocodes the addresses you enter on Resource and Phase records.

Check the address fields on your page layouts

Precursive geocodes an address only when the address fields hold data, so your users need those fields on their layouts. Precursive ships them in an Address section on the Resource Default Layout and the Phase Layout, so most orgs have nothing to do here.

Open a Resource record and a Phase record, and confirm that your users see all five fields. If your org uses a layout of its own and a field is missing, add it:

1. Go to Setup > Object Manager > Phase.
2. Select Page Layouts, then open the layout your users work with.
3. Drag the field from the Fields section of the top pane onto the layout, then select Save.
4. Go to Setup > Object Manager > Resource, then repeat steps 2 and 3 for the Resource page layout.

Precursive stores the coordinates it receives from Google in the Geolocation field (preempt__geolocation__c). This field is not on the default layouts, and your users do not need it: the Distance filter reads the coordinates directly.

Add addresses to your Resources and Phases

The Distance filter returns a Resource only when both the Phase and the Resource hold coordinates, so fill in the address fields on the records you plan to search.

• Precursive geocodes a record when you save an address. Precursive sends the address to Google when you create a record with an address, and again whenever you change one of the address fields on an existing record.
• Existing records keep their current values until you save them again. Records that held an address before you entered the API key have no coordinates yet. Edit and save them, or run a bulk update across the address fields, and Precursive geocodes them.
• An empty address clears the coordinates. When you remove the address from a record, Precursive clears the stored coordinates, and the Distance filter no longer returns that record.

You can update the addresses record by record, or in bulk through Data Loader or a list view.

Check that Proximity Search works

1. Confirm that at least one Phase and one Resource hold a complete address.
2. Go to the Resource Plan, and set Show to Unassigned to list the open Resource Requests.
3. Select Assign next to a Resource Request on a Phase that holds an address.
4. In the filtering pane that opens on the right, under Distance, select Add filter.
5. Populate the fields in the window that opens:

   • Set Field to Distance.
   • Choose an Operator.
   • Enter a Value.
   • Choose a Unit.
   • Select Done.
6. Select Apply at the top of the filtering pane, and confirm that Precursive returns the Resources near that Phase location.

For the full usage steps, see Resource Plan.

If the results do not match your expectations, check the following:

Related resources

• Resource Plan
• Geocoding API Usage and Billing
• Getting Started with Google Maps Platform
• Restrict Your API Keys