Queries and Feature Collections

Geospatial applications typically work with subsets of features in a library, such as buildings in a town, or waterways in a particular region. These subsets are represented as feature collections, which are the result of queries.

Feature collections are lightweight objects that merely described what should be returned; they don’t actually contain any objects and take up minimal space. In other words, query execution is lazy: Features are fetched only once they are needed, in response to iteration or a call to count().
Feature collections can be ordered or unordered. Only the nodes of a way and the members of a relation are ordered; all other query results are returned in arbitrary order.

Start working with collections by creating a root collection, which contains all features in a given Geographic Object Library:

Features(const char* golFileName);

From this collection, you can create others:

Features france("path/to/france.gol");
...
Features shops = france("na[shop]");
Features thingsInParis = france(paris);  // Feature or geometry 
Features shopsInParis = shops & thingsInParis;

Filtering features

To select a subset of Features, add the constraint in parentheses, or apply a filter method. This always creates a new collection, leaving the original Features object unmodified.

By bounding box

Select the features whose bounding boxes intersect the given Box:

Features france("france.gol");
Box parisBounds = Box::ofWSEN(
    2.2, 48.8, 2.5, 48.9);
Features thingsInParis = france(parisBounds);

By type and tags

Apply a query written in GOQL (Geographic Object Query Language) to select features based on their type and tags:

Features restaurants = world(
    "na[amenity=restaurant]");   
    // nodes and areas
    
Nodes fireHydrants = world(
    "n[emergency=fire_hydrant]");
    // only nodes
    
Ways safeForCycling = world(
    "w[highway=cycleway,path,living_street],"        
    "w[highway][maxspeed < 30]");
    // linear ways

Using filter methods

Apply a spatial filter or topological filter, or a custom filter:

states.within(usa)
features("w[highway]").membersOf(route66)
parks.filter(MyFilters::containsWaterFountains);

Using set intersection

Select only features that are in both sets:

Features museums = world("na[tourism=museum]");
Features inParis = world.within(paris);
Features parisMuseums = museums(inParis);

Alternatively, you can use the & operator:

Features parisMuseums = museums & inParis;

Obtaining `Feature` objects

Simply iterate:

for(Feature hotel : hotels)
{
    std::cout << hotel["name"] << std::endl;
}

Create a std::vector, or populate an existing one:

std::vector<Feature> list = streets;
streets.addTo(myVector);

Check if the set is empty:

if (pubs.within(dublin))
    printf("Great, we can grab a beer in this town!");

if (!street.nodes("[traffic_calming=bump]"))
    printf("No speed bumps on this street.");

Obtaining a single `Feature`

first

Returns the first feature in a collection:

std::optional<Feature> city = france("n[place=city][name=Paris]").first();

Note that only the nodes of ways and members of relations are ordered collections; all others are unordered sets, which means you’ll receive a random feature if there are more than one. If the collection is empty, first() returns nullopt.

one

Returns the one and only feature of the collection. Throws a QueryException if the collection is empty or contains more than one feature.

Feature paris = world("n[place=city][name=Paris]").one();
    // will likely throw a QueryException, 
    // because there's also Paris, Texas

Testing for membership

To check if a feature belongs to a given set, use contains():

Features sushiRestaurants = 
    world("na[amenity=restaurant][cuisine=sushi]");

if (sushiRestaurants.contains(restaurant))
    std::cout << restaurant["name"] << " serves sushi";

Scalar queries

count

The total number of features in the collection:

printf("%d restaurants found.", restaurants.count());

area

The total area (square meters as double) of all areas in this set.

printf("London has %f square meters of parks.", 
    parks.within(london).area());

length

The total length (meters as double) of all features in this set. For areas, their circumference is used.

printf("The French motorway network is %f km long.", 
    france("w[highway=motorway]").length() / 1000);

Spatial filters

Features can be filtered by their spatial relationship to other geometric objects (typically a GEOSGeometry or another Feature).

containing

Selects features whose geometry contains A:

Every point of A is a point of the candidate feature, and the interiors of the two geometries have at least one point in common.

Features containing(Feature);
Features containing(GEOSGeometry);
Features containingXY(Coordinate);
Features containingLonLat(double, double);

For example:

// In which park (if any) is this statue of Claude Monet?
return features("a[leisure=park]")
    .containing(statueOfMonet).first();

// The county, state and country for this point -- should return 
// San Diego County, California, USA (in no particular order)  
return features("a[boundary=administrative][admin_level <= 6]")
    .containingLonLat(-117.25, 32.99); 

coveredBy

Selects features whose geometry is covered by A:

No point of the candidate feature’s geometry lies outside of A.

Features coveredBy(Feature);
Features coveredBy(GEOSGeometry);

crossing

Selects features whose geometry crosses A:

The geometries of A and the candidate feature have some (but not all) interior points in common
The dimension of the intersection must be less than the maximum dimension of the candidate and A.

Features crossing(Feature);
Features crossing(GEOSGeometry);

For example:

// All railway bridges across the Mississippi River
Features railwayBridges = features("w[railway][bridge]");    
return railwayBridges.crossing(mississippi);

intersecting

Selects features whose geometry intersects A:

The geometries of A and the candidate feature have at least one point in common.

Features intersecting(Feature);
Features intersecting(GEOSGeometry);

maxMetersFrom

Selects features whose distance to A is less or equal to m meters (measured between the closest points of the candidate feature and A).

Features maxMetersFrom(double, Feature);
Features maxMetersFrom(double, GEOSGeometry);
Features maxMetersFrom(double, Coordinate);
Features maxMetersFromLonLat(double, double, double);

For example:

// All bus stops within 500 meters of the given restaurant
Features nearbyBusStops = features("n[highway=bus_stop]")
    .maxMetersFrom(500, restaurant);
 
// All features within 3 km of the given point 
return features.maxMetersFromLonLat(3000, 76.41, 40.12); 

within

Selects features that lie entirely within A:

Every point of the candidate feature is a point in A, and their interiors have at least one point in common.

Features within(Feature);
Features within(GEOSGeometry);

Topological filters

These methods return a subset of those features that have a specific topological relationship with another Feature.

connectedTo

Selects all features that have at least one node (vertex) in common with the given Feature or Geometry.

Features connectedTo(Feature);
Features connectedTo(GEOSGeometry);

nodesOf

The nodes of the given way. Returns an empty set if the feature is a Node or Relation.

Nodes nodesOf(Feature);

membersOf

Features that are members of the given relation, or nodes of the given way. Returns an empty set if the feature is a Node.

Features membersOf(Feature);

parentsOf

Relations that have the given feature as a member, as well as ways to which the given node belongs.

Features parentsOf(Feature);

Custom filters

Use filter() with your own filter predicate:

// Find all parks whose area is at least 1 km²
// (one million square meters)
 
Features parks = world("a[leisure=park]");
Features largeParks = parks.filter([](Feature park)
    { return park.area() > 1'000'000; });

Important: The predicate must be threadsafe, as the query may be executed in parallel.

Queries and Feature Collections

Filtering features

By bounding box

By type and tags

Using filter methods

Using set intersection

Obtaining Feature objects

Obtaining a single Feature

first

one

Testing for membership

Scalar queries

count

area

length

Spatial filters

containing

coveredBy

crossing

intersecting

maxMetersFrom

within

Topological filters

connectedTo

nodesOf

membersOf

parentsOf

Custom filters

Obtaining `Feature` objects

Obtaining a single `Feature`