Location-Based Filters

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.

query accounts {
  uiapi {
    query {
      Account{
        edges {
          node {
            Id
            Name {
              value
            }
            Location__Latitude__s {
              value
            },
            Location__Longitude__s {
              value
            }
          }
        }
      }
    }
  }
}

The previous query is similar to the following SOQL statement.

SELECT Name, Location__latitude__s, Location__longitude__s
FROM 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.

Account(where: {
  Location__c: {
    lt: {
        latitude: 47.6062
        longitude: 122.3321
        radius: 500
        unit: MI
      }
    }
  }) {
        edges {
          node {
            DisplayValue
          }
        }
      }

The previous query is similar to the following SOQL statement.

WHERE 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.

query {
  uiapi {
    query {
      Account(orderBy:{
        Location__c:{
          distance:{
            latitude:47.6062
            longitude:122.3321
          },
          nulls:LAST
          order:ASC
        }
      }) {
        edges {
          node {
            Id
            Name {
              value
            },
            Location__Latitude__s {
              value
            },
            Location__Longitude__s {
              value
            }
          }
        }
      }
    }
  }
}

The previous query is similar to the following SOQL statement.

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

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

query {
  uiapi {
    query {
      Account(where: {
        Location__c: {
          lt: {
             Latitude: 47.6062
             Longitude: 122.3321
             radius: 500
             unit: MI
           }
         }
       },
       orderBy: {
         Location__c: {
           distance: {
             latitude: 47.6062
             longitude: 122.3321
           }
          }
        }) {
          edges {
            node {
              Id
              Name {
                value
              },
              Location__Latitude__s {
                value
              },
              Location__Longitude__s {
                value
              }
            }
          }
        }
      }
   }
}

The previous query is similar to the following SOQL statement.

SELECT Id, Name
FROM Account
WHERE DISTANCE(Location__c, GEOLOCATION(47.6062,-122.3321), 'mi') < 500
ORDER 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.

edges{
  node{
    Name {
      value
    },
    Location__c { # don't do this
      value
    }
  }
}

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.

query AccountLocations {
  uiapi {
    query {
      Account (where: { Location__Latitude__s: { ne: null }}){
        edges {
          node {
            Id
            Name {
              value
            }
            Location__c { # Geolocation compound field
              Location__Latitude__s { # Constituent field
                value
              },
              Location__Longitude__s { # Constituent field
                value
              }
            }
          }
        }
      }
    }
  }
}

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.

See Also

Field Operators: Geolocation Field Types

Object Reference: Geolocation Compound Field

SOQL and SOSL Reference: Location-Based SOQL Queries

SOQL SELECT Syntax: Order By