lta-rs

🚍 Singapore LTA Datamall Rust Client written in pure rust with support for asynchronous requests. lta-rs is used to interact with the lta-datamall

lta-rs in action

Cargo.toml setup

```toml [dependencies]

features available: async, blocking, all. If you only need blocking requests, choose blocking vice versa.

lta = { version = "0.3.0", features = ["blocking", "async"] } ```

API key setup

You can get your API key from here

```rust

use lta::prelude::*;

fn main() { let apikey = "MYAPIKEY"; let client = LTAClient::withapikey(apikey); } ```

Examples

Getting bus timings

```rust use lta::prelude::*; use lta::blocking::ltaclient::LTAClient; use lta::blocking::bus::getarrival;

fn getbusarrival() -> LTAResult<()> { let apikey = std::env::var("APIKEY").expect("APIKEY not found!"); let client = LTAClient::withapikey(apikey); let arrivals: BusArrivalResp = get_arrival(&client, 83139, None)?; println!("{:?}", arrivals); Ok(()) } ```

Getting other data

``rust // All the APIs in this library are designed to be used like this //lta::blocking::module::getsomething` // All of them return lta::utils::LTAResult> // The example below is bus::getbusservices() // and traffic::geterprates() // Do note that the API calling convention is similar across all the APIs except for // bus::getarrival // prefer lta::prelude::* over glob imports use lta::prelude::*; use lta::blocking::{ ltaclient::LTAClient, traffic::geterprates, bus::getbus_services, };

fn busservices() -> LTAResult<()> { let apikey = std::env::var("APIKEY").expect("APIKEY not found!"); let client = LTAClient::withapikey(apikey); let busservices: Vec = getbusservices(&client)?; println!("{:?}", bus_services); Ok(()) }

fn geterp() -> LTAResult<()> { let apikey = std::env::var("APIKEY").expect("APIKEY not found!"); let client = LTAClient::withapikey(apikey); let erprates: Vec = geterprates(&client)?; println!("{:?}", erp_rates); Ok(()) } ```

Async Example

Using std::future and tokio

```rust use std::env; use lta::prelude::*; use lta::r#async::{ bus::getarrival, ltaclient::LTAClient };

#[tokio::main]
async fn fut() -> LTAResult<()> {
    let api_key = env::var("API_KEY").expect("API_KEY must be set!");
    let client = LTAClient::with_api_key(api_key);
    let f1 = get_arrival(&client, 83139, None).await?;
    let f2 = get_arrival(&client, 83139, None).await?;
    println!("{:?} \n{:?}", f1, f2);
    Ok(())
}

```

Custom Client

There are some instances where you might need to customise the reqwest client due to certain limitations.

```rust use lta::prelude::*; use std::time::Duration; use lta::utils::reqwest::blocking::ClientBuilder; use lta::blocking::lta_client::LTAClient;

fn mycustomclient() -> LTAClient { let client = ClientBuilder::new() .gzip(true) .connect_timeout(Some(Duration::new(420,0))) .build() .unwrap();

LTAClient::new(Some("api_key".to_string()), client)

} ```

Concurrent requests without `Futures`

Using normal threads

```rust use std::sync::Arc; use std::thread::spawn; use lta::blocking::{ ltaclient::LTAClient, traffic::getcarpark_avail, }; use lta::prelude::*;

fn concurrent() { let apikey = env::var("APIKEY").unwrap(); let c1 = Arc::new(LTAClient::withapikey(api_key)); let c2 = c1.clone();

let child = spawn(move || {
    let res = get_carpark_avail(&c1).unwrap();
    println!("{:?}", res)
});

let vms = traffic::get_vms_emas(&c2).unwrap();
println!("{:?}", vms);

child.join();

} ```

General advice

Reuse LTAClient as it holds a connection pool internally
Reduce the number of times you call the API, take a look at Update Freq in the documentation and prevent yourself from getting blacklisted. Use a caching mechanism.
Prefer async APIs over writing your own implementations for concurrent requests.

Getting help

You can get help via GitHub issues. I will try my best to respond to your queries :smile:

Design decisions

Made sure that Rust structs are as close to the original response as possible so that people can reference the original docs if there are any issues
Simple and no additional baggage. Only the client is included. E.g If anyone wants to add concurrency, they have to do it on their own
Predictable API usage

Changelog

Changelog can be found here

Requirements

On Linux:

OpenSSL 1.0.1, 1.0.2, or 1.1.0 with headers (see https://github.com/sfackler/rust-openssl)

On Windows and macOS:

Nothing.

lta-rs uses rust-native-tls internally, which will use the operating system TLS framework if available, meaning Windows and macOS. On Linux, it will use OpenSSL 1.1.

Todo (excluding bugs from issues)

[x] Proper date types using chrono library
[x] Utils cleanup
[x] Host on crates.io
[ ] Static website to showcase project
[x] Documentation
[x] More idiomatic Rust code
[x] Asynchronous requests
[x] Travis CI
[x] Documentation for async
[x] std::future
[x] Customisable Client
[x] Better testing, reduce API spam and cache data for testing
[ ] Deserialization benchmark

License

lta-rs is licensed under MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

Frequently Asked Questions

Is this library being actively developed?

Yes. However, development will slow down from mid August 2019 onwards due to my NS commitments.

What are the APIs available?

Take a look at the official LTA docs.

Where do I get the official docs from lta?

You can get them here

Why are some of the data types different from the lta documentation?

Some of the data types returned are not ideal such as returning lat and lang as string rather than number. Some of the types are also converted to enums to reduce the number of stringly typed stuff

My application panicked.

Check if your API key is valid, if it is and your application still panics because of this library, create a github issue

Why is the most fully featured LTA client library implemented in a language not many people use?

Friendship ended with Kotlin. Now Rust is my best friend ❤️.

Is this project affiliated to LTA or any government body?

No.