Location-Based Filters

AVAILABLE API VERSION
API v57.0 and later
Compound fields available in API v59.0 and later

Run a query on a geolocation field for a supported object using the GeolocationInput type. The geolocation custom field types stores location values on records using latitude and longitude values. You can create queries that calculate the distance between two location values or between a location value and a latitude-longitude coordinate.

To create a location-based filter, use the where and orderBy arguments.

Query Records with Geolocation Fields

A compound geolocation field includes latitude and longitude values. To work with compound geolocation fields, reference the individual components of the returned value. For example, if your geolocation field name is Location, use the Location__Latitude__s and Location__Longitude__s.

1query accounts {
2  uiapi {
3    query {
4      Account{
5        edges {
6          node {
7            Id
8            Name {
9              value
10            }
11            Location__Latitude__s {
12              value
13            },
14            Location__Longitude__s {
15              value
16            }
17          }
18        }
19      }
20    }
21  }
22}

The previous query is similar to the following SOQL statement.

1SELECT Name, Location__latitude__s, Location__longitude__s
2FROM Account

Filter Using where

Pass in the where argument to filter records based on a geolocation compound field. Let’s say you have a custom geolocation field Location__c on accounts. This where argument finds accounts that are within 500 miles of 47.6062°, -122.3321° (Seattle, WA) using the lt function.

1Account(where: {
2  Location__c: {
3    lt: {
4        latitude: 47.6062
5        longitude: 122.3321
6        radius: 500
7        unit: MI
8      }
9    }
10  }) {
11        edges {
12          node {
13            DisplayValue
14          }
15        }
16      }

The previous query is similar to the following SOQL statement.

1WHERE DISTANCE(Location__c, GEOLOCATION(47.6062,-122.3321), 'mi') < 500

Order Results Using orderBy

Given a set of records with geolocation fields, you can sort them by distance using the distance filter type with the orderBy argument. You can also order the results in ascending or descending order.

The geolocation field support ordering using the OrderByClause type.

Here’s a basic query that orders the results in ascending order and null records at the end.

1query {
2  uiapi {
3    query {
4      Account(orderBy:{
5        Location__c:{
6          distance:{
7            latitude:47.6062
8            longitude:122.3321
9          },
10          nulls:LAST
11          order:ASC
12        }
13      }) {
14        edges {
15          node {
16            Id
17            Name {
18              value
19            },
20            Location__Latitude__s {
21              value
22            },
23            Location__Longitude__s {
24              value
25            }
26          }
27        }
28      }
29    }
30  }
31}

The previous query is similar to the following SOQL statement.

1SELECT Name, Location__latitude__s, Location__longitude__s
2FROM Account
3ORDER BY DISTANCE(Location__c, GEOLOCATION(47.606, 122.332), 'mi') ASC NULLS LAST

The following example adds the orderBy argument to a where argument.

1query {
2  uiapi {
3    query {
4      Account(where: {
5        Location__c: {
6          lt: {
7             Latitude: 47.6062
8             Longitude: 122.3321
9             radius: 500
10             unit: MI
11           }
12         }
13       },
14       orderBy: {
15         Location__c: {
16           distance: {
17             latitude: 47.6062
18             longitude: 122.3321
19           }
20          }
21        }) {
22          edges {
23            node {
24              Id
25              Name {
26                value
27              },
28              Location__Latitude__s {
29                value
30              },
31              Location__Longitude__s {
32                value
33              }
34            }
35          }
36        }
37      }
38   }
39}

The previous query is similar to the following SOQL statement.

1SELECT Id, Name
2FROM Account
3WHERE DISTANCE(Location__c, GEOLOCATION(47.6062,-122.3321), 'mi') < 500
4ORDER BY DISTANCE(Location__c, GEOLOCATION(47.6062,-122.3321), 'mi')

Location-Based Query Limitations

When you query geolocation compound fields, use the constituent fields in the query.

1edges{
2  node{
3    Name {
4      value
5    },
6    Location__c { # don't do this
7      value
8    }
9  }
10}

Provide a direct reference to the internal primitive data types. For example, use Location__Latitude__s and Location__Longitude__s if you have a compound geolocation field Location__c.

1query AccountLocations {
2  uiapi {
3    query {
4      Account (where: { Location__Latitude__s: { ne: null }}){
5        edges {
6          node {
7            Id
8            Name {
9              value
10            }
11            Location__c { # Geolocation compound field
12              Location__Latitude__s { # Constituent field
13                value
14              },
15              Location__Longitude__s { # Constituent field
16                value
17              }
18            }
19          }
20        }
21      }
22    }
23  }
24}

Similar to how SOQL calculates and compares distances, you can’t check locations or distances for equality with GraphQL API. You can only determine whether a location is farther or closer than another location, or one distance is greater or smaller than another.

Location-Based Filters

Query Records with Geolocation Fields

Filter Using where

Order Results Using orderBy

Location-Based Query Limitations

See Also