Sets of Features

A feature set represents those Feature objects that meet certain criteria.

geodesk.Features(filename)

Creates a feature set based on a Geographic Object Library.

france = Features("france")   # All features in france.gol

Filtering features

To select a subset of features, add the constraint in parentheses, or apply a filter method. This always creates a new feature set, leaving the original set unmodified.

By bounding box

Select the features whose bounding boxes intersect the given Box:

paris_bounds = Box(
    west=2.2, south=48.8,
    east=2.5, north=48.9)
features_in_paris = france(paris_bounds)

By type and tags

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

restaurants = features(
    "na[amenity=restaurant]")
    # nodes and areas

fire_hydrants = features(
    "n[emergency=fire_hydrant]")
    # only nodes

safe_for_cycling = features(
   "w[highway=cycleway,path,living_street],"
   "w[highway][maxspeed < 30]")
   # linear ways

Using filter methods

Apply a spatial filter, geometric filter or topological filter:

states.within(usa)
features("w[highway]").members_of(route66)

Using set intersection

Select only features that are in both sets:

museums  = features("na[tourism=museum]")
in_paris = features.within(paris)
paris_museums = museums(in_paris)

Alternatively, you can use the & operator:

paris_museums = museums & in_paris

Obtaining `Feature` objects

Iterate through the feature set:

>>> for hotel in hotels:
...     print(hotel.name)
Hôtel du Louvre
Ambassadeur
Brit Hotel

Turn it into a list:

>>> list(hotels)
[way/112112065, relation/1575507, node/3558592188]

Check if the set is empty:

if pubs(within_dublin):
    print("Great, we can grab a beer in this town!")

if not street.nodes("[traffic_calming=bump]"):
    print("No speed bumps on this street.")

Obtaining a single `Feature`

Features.first

The first feature of the set (or any arbitrary feature if the set is unordered).

None if the set is empty.

Features.one

The one and only feature of the set.

A QueryError is raised if the set is empty or contains more than one feature.

Alternatively, use [0] to get the first Feature of a non-empty set.

A QueryError is raised if the set is empty.

first_node = way.nodes[0]

Testing for membership

To check if a feature belongs to a given set, use the in operator:

sushi_restaurants = world("na[amenity=restaurant][cuisine=sushi]")

if restaurant in sushi_restaurants:
    print (f"{restaurant.name} serves sushi")

Result properties

These are read-only, and are calculated on each access.

Features.count

The total number of features in this set.

Features.area

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

Features.length

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

Features.shape

A GeometryCollection that contains the shapes of all features in this set.

Subsets

Features.nodes

Only features that are nodes.

Features.ways

Only features that are ways (including areas that are represented using a closed way).

If you want to restrict the subset to linear ways, use features('w').

Features.relations

Only features that are relations (including relations that represent areas).

If you want to restrict the subset to non-area relations, use features('r').

Formatting

Features.geojson

The set’s features as GeoJSON (Formatter)

Features.geojsonl

The set’s features as GeoJSON, with each feature on a separate line (Formatter)

Features.map

A Map that displays the features in this set. Use show() to open it in a browser window, or save() to write its HTML file.

restaurants.map.show()
hotels.map.save("hotel-map") # .html by default
hydrants.map(color='red')    # map with fire hydrants marked in red

Features.wkt

The set’s features as Well-Known Text (Formatter)

Spatial filters

These methods return a subset of only those features that fulfill a specific spatial relationship with another geometric object (Feature, Geometry, Box or Coordinate).

Features.within(geom)

Features that lie entirely inside geom.

Features.around(geom, units=distance)

Features that lie within the given distance from the centroid of geom. In lieu of a geometric object, you can also specify coordinates using x and y (for Mercator-projected coordinates) or lon and lat (in degrees). Use meters, feet, yards, km, miles or mercator_units to specify the maximum distance.

# All bus stops within 500 meters of the given restaurant
features("n[highway=bus_stop]").around(restaurant, meters=500)

# All features within 3 miles of the given point
features.around(miles=3, lat=40.12, lon=-76.41)

Features.contains(geom)

Features whose geometry contains the given geometric object.

Note: If you want to test whether this set includes a particular feature, use feature in set (See above)

# In which park (if any) is this statue of Claude Monet?
features("a[leisure=park]").contains(statue_of_monet).first

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

As of Version 0.2.0, only nodes and Coordinate objects are supported.

Features.crosses(geom)

Features whose geometry crosses the given geometric object.

# All railway bridges across the Mississippi River
features("w[railway][bridge]").crosses(mississippi)

Features.disjoint(geom)0.2

Features whose geometry is disjoint from the given geometric object.

Features.intersects(geom)

Features whose geometry intersects the given geometric object.

Features.overlaps(geom)0.2

Features whose geometry overlaps the given geometric object.

Features.touches(geom)0.2

Features whose geometry touches the given geometric object.

Features.nearest_to(geom, units=distance)0.2

Features in ascending order of distance to the given geometric object.

To limit the search radius, specify a maximum distance in the units of your choice: meters, feet, yards, km, miles or mercator_units

features("na[amenity=hospital]").nearest_to(my_location, miles=5)

Geometric filters

These methods return a subset of those features that have specific geometric properties.

Features.min_area(n)

Features whose area is at least n, where n can be square meters or a specific unit (meters, feet, yards, km, miles or mercator_units).

buildings.min_area(1000)
# Buildings with a footprint of at least a thousand square meters

world("a[place=island]").min_area(miles=500)
# Islands that are at least 500 square miles

Features.max_area(n)

Features whose area is at most n (see min_area above).

features("a[leisure=pitch][sport=tennis]").max_area(ft=2000)
# Tennis courts that are no more than 2000 quare feet

Features.min_length(n)

Features whose length is at least n, where n can be meters or a specific unit (meters, feet, yards, km, miles or mercator_units).

features("w[barrier=hedge]").min_length(300)
# Hedges that are at least 300 meters long

rivers.min_length(km=30)
# Rivers whose length is at least 30 kilometers

Features.max_length(n)

Features whose length is at most n (see min_length above).

streets.max_length(2.5)
# Street segments that are 2.5 meters or less

Topological filters

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

Features.nodes_of(feature)

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

Features.members_of(feature)

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

Features.parents_of(feature)

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