Developers · Data

Distance Units

Last updated 1 November 2026

The distance units for distance sorting, and the kilometer-only geo filters on records and users.

Distance units choose how a distance is measured when you sort results by how far they are from a point. This page lists the units, and explains which queries use them and which always work in kilometers.

The units

Unit	Value
Centimeters	`cm`
Meters	`m`
Kilometers (the default)	`km`
Yards	`yd`
Miles	`mi`
Nautical miles	`nmi`

These are the values of the DistanceUnit enum. Write them without quotes, for example unit: mi.

Where the unit applies

The unit is an argument of a distance sort, which takes the location field, a reference point and the unit:

sort: {
  distance: {
    field_name: "geo_location"
    reference_point: { lat: -27.47, lng: 153.03 }
    unit: km
  }
}

This sort belongs to the deprecated listings and people queries. profile_distance does the same with user profile addresses.

Records and users work in kilometers

For new work, filter records or users on a geojson property. These filters take kilometers only:

properties: [{
  name: "location"
  distance_sphere: {
    center: { type: "Point", coordinates: [153.03, -27.47] }
    distance_in_km: 10
    sort: ASC
  }
}]

Filter	Matches
`distance_sphere`	Records closer than `distance_in_km` to `center`, ordered by distance (`ASC`, `DESC` or `NONE`)
`within_radius`	Records within a radius stored in another Float property of the same record, in kilometers
`not_within_radius`	Records outside that radius

To show a distance in miles, convert it in Liquid after the query.

Note

The docs instance has no location data, so these examples were not run. They follow the GraphQL schema.

Common mistakes

Writing coordinates in the wrong order. GeoJSON puts longitude first; reference_point uses named lat and lng.
Looking for a unit argument on distance_sphere. There is none: it is always kilometers.
Expecting a record exactly at distance_in_km to match. It does not.