Skip to main content Link Search Menu Expand Document (external link)

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 intersects 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 (the 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 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]

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 represented as GeoJSON (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 represented 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.

Example:

# 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.

# 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.1.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

Example:

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

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.descendants_of(feature)0.2

Features.ancestors_of(feature)0.2

Features.connected_to(feature)

All features that share a common node with feature.

Metadata 0.2

Features.properties

Features.license

The license under which this dataset is made available.

Features.license_url

The URL where the text of the license can be found.

Features.indexed_keys

Features.tiles


Table of contents