Proximity searches

A proximity search is a type of contact search in which the search criteria include an address and a distance. The search results include only the contacts whose primary address fits the search criteria.

You can do a proximity search for all contacts within a given radius of the search address.
- For example, a proximity search to find all auto repair shops within 10 miles of 1431 Helman Road, Los Angeles, California.
You can do a proximity search for the N contacts closest to the search address.
- For example, a proximity search to find the 5 auto repair shops closest to 1431 Helman Road, Los Angeles, California.

Theoretically, a proximity search can be executed for any type of contact from any core application. In practice, proximity searches are typically done only for vendors, and only at the request of ClaimCenter. This is because vendors provide services for claims, and it is common to want to identify only the vendors who are conveniently close to who needs the service or where the service must occur.

Within the context of proximity searches, address information is specified as longitude and latitude coordinates.

The search criteria must specify longitude and latitude.
- If the search is executed from the ContactManager user interface, the search criteria can specify an address that can be converted into longitude and latitude by a geocoding service.
- If the search is executed from Cloud API, it must specify longitude and latitude directly.
For every contact that may need to be returned in a search result, the longitude and latitude of the contact's primary address must be stored in the ContactManager database.
- This is typically done by a batch process that identifies any addresses in the database without longitude and latitude coordinates, queries a geocoding service to convert the address into longitude and latitude coordinates, and then stores those coordinates in the database as part of the address.

Note: Any addresses without longitude and latitude coordinates are inherently excluded from proximity search results.

You can execute a proximity search in miles or kilometers.

For more information on how ContactManager uses geocoding to provide longitude and latitude for addresses, refer to the Contact Management Guide.

Basic proximity searches

Proximity searches are executed using the POST /contacts/v1/search/contacts endpoint. The minimum amount of information needed for a meaningful proximity search are:

The contact subtype
The search criteria address, specified as longitude and latitude coordinates
The radius
- In the base configuration, this defaults to 300 miles.

The following identifies the syntax for the request payload for a basic proximity search:

{
  "data": {
    "attributes": {
        "contactSubtype": {
            "code": "<codeForContactSubtype>"
        },
        "coordinates": {
            "longitude": "<decimalValueAsString>",
            "latitude": "<decimalValueAsString>"
        },
        "radius": <integerValue>
    }
  }
}

For example, the following payload could be used to identify all ABCompany contacts within 10 miles of longitude -122.26842 and latitude 37.55496 (which is in San Mateo, California).

POST /contacts/v1/search/contacts

{
  "data": {
    "attributes": {
        "contactSubtype": {
            "code": "ABCompany"
        },
        "coordinates": {
            "longitude": "-122.26842",
            "latitude": "37.55496"
        },
        "radius": 10
    }
  }
}

If that payload is executed against the sample data, it produces the following results:

{
    "count": 3,
    "data": [
        {
            "attributes": {
                "displayName": "M B Garage",
                "id": "ab:77",
                ...
            },
            "attributes": {
                "displayName": "Burlingame Saab",
                "id": "ab:78",
                ...
            },
            "attributes": {
                "displayName": "Menlo Park Chevron",
                "id": "ab:79",
                ...
            }
       ]
...

Specifying a radius and unit of distance

A proximity search can specify a radius and a unit of distance. For example, the following JSON payload executes a proximity search with a radius of 10 kilometers.

{
  "data": {
    "attributes": {
        "contactSubtype": {
            "code": "ABCompany"
        },
        "coordinates": {
            "longitude": "-122.26842",
            "latitude": "37.55496"
        },
        "radius": 10,
        "unitOfDistance": {
          "code": "Kilometer"
    }
  }
}

Specifying radius size

The radius field is optional. If you do not specify a value, ContactManager sets the search radius to the value of the ProximitySearchOrdinalMaxDistance configuration parameter in config.xml. In the base configuration, this parameter is set to 300.

Specifying unit of measurement

The unitOfDistance field is optional. If you do not specify a value, the unit of measure ContactManager uses depends on the UseMetricDistancesByDefault configuration parameter in config.xml.

In the base configuration, this parameter is set to false, which means that, by default, radius distances are treated as miles.
If this parameter is set to true, then by default radius distances are treated as kilometers.

When you include the unitOfDistance field in a given search, you must set it to a typecode in the UnitOfDistance typelist. In the base configuration, the valid codes are: Feet, Kilometer, Meter, Mile. Once included, the value of this field overrides the UseMetricDistancesByDefault configuration parameter.

For more information on configuration parameters in config.xml, refer to the Configuration Guide.

Limiting results to the N closest contacts

One common use case for proximity searches is to find the N closest contacts to a given location. For example, if a car was damaged and needs to be towed, you might want to identify the 5 closest auto towing services.

Search results are inherently sorted by distance from the search criteria address. Therefore, you can use the pageSize query parameter to limit the search results to the first N values, which will be the N closest values. (The pageSize query parameter consists of an integer N that controls pagination. If the number of results is greater than the integer, the first call includes only the first N results.)

For example, the following payload could be used to identify the 5 closest ABAutoRepairShops within 10 miles of longitude -122.26842 and latitude 37.55496 (which is in San Mateo, California).

POST /contacts/v1/search/contacts?pageSize=5

{
  "data": {
    "attributes": {
        "contactSubtype": {
            "code": "ABAutoRepairShop"
        },
        "coordinates": {
            "longitude": "-122.26842",
            "latitude": "37.55496"
        },
        "radius": 10
    }
  }
}