Crate overpass_lib

Expand description

Easily create and execute Overpass API queries of OpenStreetMap. Supports both declarative and builder syntax for generating OverpassQL strings, a reqwest-based submission API, and type definitions for handling the query results.

§Usage

Just like in OverpassQL, you specify a Set of Elements that you want, defined either as a basic FilterSet or as compositions of other sets (e.g. UnionSet). You can either define these structs directly, or use SetBuilder for more convenient syntax.

Once your set is specified, you:

Convert it to a Query or QueryBuilder,
Apply any top-level settings to the query (e.g. Query::search_bbox),
Evaluate the query via an Overpass API server (OverpassServer),
Do whatever you like with the Elements returned!

§Examples

// Let's find all the landmarks in downtown Seattle in a standard OverpassQL string.
let oql = [
    "[bbox:47.553,-122.461,47.667,-122.201][out:json];",
    r#"nw["seamark:type"="landmark"];"#,
    "out;",
].join("");
 
// Using the declarative syntax, it looks like this:
let dec_query = Query {
    set: FilterSet {
        filter_type: FilterType::NodeOrWay,
        tag_filters: HashSet::from([TagFilter::equals("seamark:type", "landmark")]),
        ..Default::default()
    }.into(),
    search_bbox: Some(Bbox {
        north: 47.667, 
        south: 47.553,
        east: -122.201,
        west: -122.461, 
    }),
    ..Default::default()
};
assert_eq!(&oql, &dec_query.to_oql());
 
// Using the builder API it looks like this:
let builder_query: Query = SetBuilder::all_nodes_or_ways()
    .with_tag_value("seamark:type", "landmark")
    .to_query()
    .search_bbox(Bbox {
        north: 47.667,
        south: 47.553,
        east: -122.201,
        west: -122.461,
    })
    .into();
assert_eq!(&oql, &builder_query.to_oql());

// Evaluate the query via the default Overpass API server
let res = OverpassServer::default().evaluate(&dec_query).await.unwrap();

// One of those landmarks should be the Space Needle.
assert!(res.elements.iter().any(|e| matches!(e.tag("name"), Some("Space Needle"))));

§Language Support

Settings
- ✅ timeout
- ✅ maxsize
- ✅ bbox
- ✅ date
- ✅ diff
- ❌ adiff
- ❌ out count
- ✅ out verbosity
- ❌ out modificators
- ❌ out bbox
- ❌ out sort order
- ❌ out limit
Sets
- ✅ union
- ❌ difference
- ✅ intersection
- ❌ if-block
- ❌ foreach
- ❌ for
- ❌ complete
- ❌ retro
- ❌ compare
- ❌ recurse up
- ❌ recurse up relations
- ❌ recurse down
- ❌ recurse down relations
- ❌ is_in
- ❌ timeline
- ❌ local
- ❌ convert
- ❌ make
- Filters
  - ✅ has-kv
  - ✅ bbox
  - ✅ recurse refs
  - ❌ recurse way cnt/link
  - ✅ input set
  - ✅ id
  - ❌ around
  - ❌ poly
  - ❌ newer
  - ❌ changed
  - ❌ user
  - ❌ area
  - ❌ pivot
  - ❌ if
- ❌ evaluators

§Contributing

Issues and pull requests welcome through GitHub.

Structs§

Bbox: A geographic bounding box defined by two latitudes and two longitudes. Used to distinguish points inside and outside the box.
FilterSet: A subtype of Set that contains elements that satisfy the specified criteria.
FilterSetBuilder: A convenient builder API for FilterSet.
Node: A node is one of the core elements in the OpenStreetMap data model.
OverpassResult: The data returned from an Overpass Query evaluation.
OverpassServer: Makes an HTTP request to an Overpass API server to evaluate queries.
Query: The root type of this API. It serializes into a complete Overpass QL query by calling to_oql.
QueryBuilder: A convenient builder API for Query.
Relation: Relations are structured collections of objects - nodes, ways, and other relations.
RelationMember: A reference to another Node, Way, or Relation from the owning relation, with an optional role.
SaniStr: Handles string sanitization for OverpassQL queries.
SetBuilder: Provides methods to build all the various types of OverpassQL Sets.
UnionSet: A Set that is composed of all elements found in any member set.
UnionSetBuilder: A convenient builder API for UnionSet.
Way: A way is one of the fundamental elements of the map.

Enums§

Element: The basic component of OpenStreetMap’s data model. Comes in three variants: Node, Way, and Relation.
ElementId: The identifier of an Element, independent of the specific variant.
FilterType: The type of element selected by a FilterSet.
OverpassError: An error returned when a request to evaluate a Query fails.
OverpassQLError: An error returned when a Query cannot produce a valid OverpassQL query string.
QueryVerbosity: The amount of detail to be included in Query-matched Elements.
RecurseFilter: A filter set criterion based on the element’s relationship to other elements.
Set: An abstract collection of Elements selected from the full database based on given criteria.
TagFilter: The set of conditions that an element’s tags may or may not satisfy. Used to evaluate the contents of FilterSets.

Traits§

Overpass: Can retrieve Element data from OpenStreetMap that matches the provided Query set.
OverpassQL: Implementers can be represented as a full or partial OverpassQL query.
ToQuery: Trait to convert SetBuilders into QueryBuilders unambiguously in addition to Into<QueryBuilder>.
UnionWith: Trait to daisy-chain SetBuilders together into UnionSetBuilders.