overpass_lib/lib.rs
1//!
2//! Easily create and execute [Overpass API](https://wiki.openstreetmap.org/wiki/Overpass_API)
3//! queries of [OpenStreetMap](https://wiki.openstreetmap.org/wiki/About_OpenStreetMap). Supports
4//! both declarative and builder syntax for generating OverpassQL strings, a [reqwest]-based
5//! submission API, and type definitions for handling the query results.
6//!
7//! # Usage
8//!
9//! Just like in OverpassQL, you specify a [Set] of [Element]s that you want, defined either as a basic [FilterSet]
10//! or as compositions of other sets (e.g. [UnionSet]). You can either define these structs directly, or use
11//! [SetBuilder] for more convenient syntax.
12//!
13//! Once your set is specified, you:
14//!
15//! 1. Convert it to a [Query] or [QueryBuilder],
16//! 1. Apply any top-level settings to the query (e.g. [Query::search_bbox]),
17//! 1. Evaluate the query via an Overpass API server ([OverpassServer]),
18//! 1. Do whatever you like with the [Element]s returned!
19//!
20//!
21//! # Examples
22//!
23//! ```
24//! # use std::collections::HashSet;
25//! # use overpass_lib::*;
26//! # tokio::runtime::Builder::new_current_thread().enable_all().build().unwrap().block_on(async {
27//! // Let's find all the landmarks in downtown Seattle in a standard OverpassQL string.
28//! let oql = [
29//! "[bbox:47.553,-122.461,47.667,-122.201][out:json];",
30//! r#"nw["seamark:type"="landmark"];"#,
31//! "out;",
32//! ].join("");
33//!
34//! // Using the declarative syntax, it looks like this:
35//! let dec_query = Query {
36//! set: FilterSet {
37//! filter_type: FilterType::NodeOrWay,
38//! tag_filters: HashSet::from([TagFilter::equals("seamark:type", "landmark")]),
39//! ..Default::default()
40//! }.into(),
41//! search_bbox: Some(Bbox {
42//! north: 47.667,
43//! south: 47.553,
44//! east: -122.201,
45//! west: -122.461,
46//! }),
47//! ..Default::default()
48//! };
49//! assert_eq!(&oql, &dec_query.to_oql());
50//!
51//! // Using the builder API it looks like this:
52//! let builder_query: Query = SetBuilder::all_nodes_or_ways()
53//! .with_tag_value("seamark:type", "landmark")
54//! .to_query()
55//! .search_bbox(Bbox {
56//! north: 47.667,
57//! south: 47.553,
58//! east: -122.201,
59//! west: -122.461,
60//! })
61//! .into();
62//! assert_eq!(&oql, &builder_query.to_oql());
63//!
64//! // Evaluate the query via the default Overpass API server
65//! let res = OverpassServer::default().evaluate(&dec_query).await.unwrap();
66//!
67//! // One of those landmarks should be the Space Needle.
68//! assert!(res.elements.iter().any(|e| matches!(e.tag("name"), Some("Space Needle"))));
69//! # });
70//! ```
71//!
72//! # Language Support
73//!
74//! * Settings
75//! * ✅ timeout
76//! * ✅ maxsize
77//! * ✅ bbox
78//! * ✅ date
79//! * ✅ diff
80//! * ❌ adiff
81//! * ❌ out count
82//! * ✅ out verbosity
83//! * ❌ out modificators
84//! * ❌ out bbox
85//! * ❌ out sort order
86//! * ❌ out limit
87//! * Sets
88//! * ✅ union
89//! * ❌ difference
90//! * ✅ intersection
91//! * ❌ if-block
92//! * ❌ foreach
93//! * ❌ for
94//! * ❌ complete
95//! * ❌ retro
96//! * ❌ compare
97//! * ❌ recurse up
98//! * ❌ recurse up relations
99//! * ❌ recurse down
100//! * ❌ recurse down relations
101//! * ❌ is_in
102//! * ❌ timeline
103//! * ❌ local
104//! * ❌ convert
105//! * ❌ make
106//! * Filters
107//! * ✅ has-kv
108//! * ✅ bbox
109//! * ✅ recurse refs
110//! * ❌ recurse way cnt/link
111//! * ✅ input set
112//! * ✅ id
113//! * ❌ around
114//! * ❌ poly
115//! * ❌ newer
116//! * ❌ changed
117//! * ❌ user
118//! * ❌ area
119//! * ❌ pivot
120//! * ❌ if
121//! * ❌ evaluators
122//!
123//! # Contributing
124//!
125//! Issues and pull requests welcome through
126//! [GitHub](https://github.com/stevenvergenz/osm-overpass-rs).
127//!
128
129#[cfg(doc)]
130use reqwest;
131
132mod osm;
133pub use osm::*;
134
135mod query;
136pub use query::*;
137
138mod overpass;
139pub use overpass::*;
140
141mod builder;
142pub use builder::*;