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.intersecting(geom)
Features whose geometry intersects the given geometric object.
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.containing(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]").containing(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]").containing(Coordinate(lon=-117.25, lat=32.99))
As of Version 0.2.1, only nodes and Coordinate objects are supported.
Features.crossing(geom)
Features whose geometry crosses the given geometric object.
# All railway bridges across the Mississippi River
features("w[railway][bridge]").crossing(mississippi)
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.
Features.connected_to(feature)
All features that share a common node with feature.