opencellid 0.2.0

Rust client library for the OpenCellID API — sync and async clients with tracing, structured errors, and bounded I/O.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80

//! Rust client for the [OpenCellID](https://wiki.opencellid.org/wiki/API) public API.
//!
//! # Features
//!
//! - `async` (default): asynchronous [`Client`] backed by `reqwest::Client`.
//!   Brings in `tokio` as a dependency.
//! - `blocking`: synchronous [`BlockingClient`] backed by `reqwest::blocking::Client`.
//! - `csv` (default): enables `cell/getInArea` (CSV-formatted bulk listing).
//! - `rustls-tls` (default) / `native-tls`: select the TLS backend. If both are
//!   enabled, `reqwest`'s default applies — prefer choosing exactly one explicitly.
//!
//! Both clients can be enabled simultaneously and share a single [`ClientBuilder`].
//!
//! # Logging
//!
//! Every public call is wrapped in a [`tracing`] span. The API key is redacted from
//! any URL emitted at `debug` level, and response bodies are length-bounded and
//! escaped before being included in error messages or `trace` events. Enable e.g.
//! `tracing_subscriber::fmt().init()` in application code to see the events.
//!
//! # Quick start (async)
//!
//! ```no_run
//! # #[cfg(feature = "async")]
//! # async fn run() -> opencellid::Result<()> {
//! use opencellid::{CellKey, ClientBuilder, Radio};
//!
//! let key = std::env::var("OPENCELLID_API_KEY")
//!     .map_err(|_| opencellid::Error::MissingConfig("OPENCELLID_API_KEY"))?;
//! let client = ClientBuilder::new().api_key(key).build()?;
//!
//! let cell = client
//!     .get_cell(CellKey::new(250, 99, 7800, 200).with_radio(Radio::Lte))
//!     .await?;
//! println!("{:?}", (cell.lat, cell.lon));
//! # Ok(()) }
//! ```

#![cfg_attr(docsrs, feature(doc_cfg))]
#![deny(missing_docs)]

#[cfg(not(any(feature = "async", feature = "blocking")))]
compile_error!(
    "opencellid: enable at least one of the `async` (default) or `blocking` features"
);

// `rustls-tls` and `native-tls` are not mutually exclusive at the Cargo level
// (so that `cargo test --all-features` and docs.rs builds succeed), but
// production users should pick exactly one. See the crate-level `# Features`
// section for guidance.

pub mod error;
pub mod params;
pub mod types;

pub(crate) mod client;
pub(crate) mod internal;

pub use client::ClientBuilder;
pub use error::{ApiErrorCode, Error, ParseError, Result, TransportError, UrlError};
pub use params::{AreaQuery, GetCellsInAreaParams};
pub use types::{
    Bbox, Cell, CellCount, CellKey, DumpKind, DumpListing, Measurement, MeasurementsPayload, Radio,
};

#[cfg(feature = "csv")]
#[cfg_attr(docsrs, doc(cfg(feature = "csv")))]
pub use internal::parse::parse_dump_csv;

#[cfg(feature = "csv")]
#[cfg_attr(docsrs, doc(cfg(feature = "csv")))]
pub use types::DumpRow;

#[cfg(feature = "async")]
#[cfg_attr(docsrs, doc(cfg(feature = "async")))]
pub use client::async_client::Client;

#[cfg(feature = "blocking")]
#[cfg_attr(docsrs, doc(cfg(feature = "blocking")))]
pub use client::blocking::BlockingClient;