Near Operator

The near operator restricts results to entities whose location falls within a given distance of a reference point. The reference point can be given in four ways: as a DQL subquery, as a street address, as an explicit latitude/longitude pair, or as an entity id.

type:Organization near(name:"San Francisco")

Syntax

near([locationField,] <reference> [, <distance>])

Part	Required	Description
locationField	No	The field on the matched entities that must fall inside the search area. Defaults to location (locations for type:Person).
reference	Yes	The point to search around: a DQL subquery, a quoted address, or a latitude, longitude pair.
distance	No	Size of the search area, e.g. 10mi or 25km. Defaults to 15km.

Specifying the reference point

By subquery

The most common form is a subquery that resolves to a place:

type:Organization near(name:"San Francisco")
type:Organization near(type:Place name:"San Francisco")
type:LocalBusiness name:"Starbucks" near(name:"Mountain View", 5mi)

DQL runs the subquery as a separate search, takes the single top-ranked result, and uses that entity's latitude and longitude as the center of the search area. If several entities match, only the most important one is used — near(name:"Springfield") searches around the most prominent Springfield in the Knowledge Graph, not all of them.

If the subquery specifies no type:, it defaults to type:AdministrativeArea, so near(name:"San Francisco") is equivalent to near(type:AdministrativeArea name:"San Francisco"). Widen it to type:Place when you want to anchor on any kind of place, including local businesses and landmarks:

type:Organization near(type:Place name:"Moscone Center", 1mi)

The reference entity does not have to be a place. Any entity type that carries a location works — Place (and its subtypes) and Organization:

type:LocalBusiness categories.name:"Mexican Restaurant" near(type:Organization name:"Diffbot", 2mi)

A subquery that resolves to an entity type without location data fails with No location was resolved from ..., and a subquery that matches nothing fails with Location query returned no matching hits.

You can also anchor on a specific entity by id or URI, which avoids the ambiguity of name matching entirely:

type:Person near(id:"A8y6iIzzkPbKiZdINSDRnYQ")
type:Organization near(diffbotUri:"https://diffbot.com/entity/A8y6iIzzkPbKiZdINSDRnYQ")

By address

Pass a quoted street address and DQL geocodes it before searching:

type:LocalBusiness near("333 Ravenswood Ave, Menlo Park, CA", 5mi)

An address that cannot be geocoded fails with Cannot resolve a valid location for ....

By latitude and longitude

This simplifies things tremendously. Pass the lat/long coordinates directly to near() in the format near(<latitude>, <longitude>, <distance>).

type:Organization near(42.316889, -83.120556, 50mi)

Specifying the location field

By default, the near operator compares the reference point against the location field of the matched entities — the field that holds the latitude and longitude of the entity. With a clause like near(name:"San Francisco"), DQL first queries for the place named San Francisco, reads its coordinates, and then keeps only those entities whose own location lies inside the search area.

That default is not always the field you want. To compare against a different location field, pass its path as the first argument, before the reference point:

near(<locationField>, <reference> [, <distance>])

For example, type:Person entities can be queried by their employer's location with employments.employer.location:

type:Person near(employments.employer.location, name:"Mountain View", 10mi)

Default location field

When no location field is explicitly given, DQL infers one from the type of the query:

Query type	Default location field
type:Person	locations
All other types	location

So type:Person near(name:"Boston") is equivalent to type:Person near(locations, name:"Boston"), and type:Organization near(name:"Boston") is equivalent to type:Organization near(location, name:"Boston").

Inside nested clauses

near() can be used inside a nested clause in DQL.

type:Person locations.{isCurrent:true near(name:"Mountain View")}
type:Person employments.{isCurrent:true employer.location:near(name:"Mountain View")}

The first query finds people whose current location is near Mountain View. The second query finds people whose current employer's location is near Mountain View.

Valid location fields

The path must point to a location object — one that has latitude and longitude subfields. Pointing at anything else is a compile error:

type:Person near(locations.city, name:"Mountain View")
→ locations.city is an illegal path for the near syntax because it does not point to a Location Type

Specifying the distance

The distance is an optional last argument, written as a whole number immediately followed by mi or km. Decimals and spaces are not accepted (10mi, not 10.5 mi).

type:Organization categories.name:"banking" near(name:"San Francisco", 10mi)
type:Organization near(name:"San Francisco", 25km)

If omitted, the distance defaults to 15km.

The search area is a box centered on the reference point whose sides are the given distance across, so entities are matched up to half the distance away in each direction. near(name:"San Francisco", 50mi) covers roughly 25 miles north, south, east and west of San Francisco. Because the area is a box rather than a circle, points near its corners are slightly farther from the center than the nominal half-distance.

Combining with other operators

near is an ordinary clause and combines with the rest of DQL as usual. Clauses written side by side must all match:

type:LocalBusiness categories.name:"Coffee Shop" near(name:"Mountain View", 5mi) sortBy:importance

It can also be wrapped in must: and should::

type:Organization name:"Starbucks" should:near(name:"Mountain View")

Legacy syntax

Two older forms remain supported and are equivalent to the forms above:

Legacy form	Modern equivalent
locations:near(name:"Boston")	near(locations, name:"Boston")
near[50mi](name:"Mountain View")	near(name:"Mountain View", 50mi)
locations:near[50mi](name:"Mountain View")	near(locations, name:"Mountain View", 50mi)

One behavioral difference: in the legacy forms a subquery with no explicit type: defaults to type:Place, whereas in the modern form it defaults to type:AdministrativeArea. New queries should use the modern syntax.

Notes and limitations

• Only the top result of the subquery is used as the reference point. To remove ambiguity, anchor on an id: or diffbotUri:, or narrow the subquery (for example with location.country.name:"United States").
• Entities missing coordinates in the requested location field are never matched, even if they carry a city or country name.
• A near clause with a subquery or an address incurs an additional entity lookup credit cost; passing coordinates directly avoids it.

Examples

Goal	Query
Organizations within 15km of San Francisco	type:Organization near(name:"San Francisco")
Banks within 10 miles of San Francisco	type:Organization categories.name:"banking" near(name:"San Francisco", 10mi)
People currently living near Boston	type:Person locations.{isCurrent:true near(name:"Boston", 25mi)}
Kotlin developers near Boston	type:Person skills.name:"Kotlin" near(locations, name:"Boston")
Restaurants near a company's headquarters	type:LocalBusiness categories.name:"Mexican Restaurant" near(type:Organization name:"Diffbot", 2mi)
Businesses near a street address	type:LocalBusiness near("333 Ravenswood Ave, Menlo Park, CA", 5mi)
Organizations near explicit coordinates	type:Organization near(42.316889, -83.120556, 50mi)
People who work near Mountain View	type:Person employments.{isCurrent:true employer.location:near(name:"Mountain View", 10mi)}