# db_ip
An (unofficial) library for querying [db-ip.com](https://db-ip.com/) CSV databases in safe Rust.
This library is not affiliated with or endorsed by [db-ip.com](https://db-ip.com/).
Be advised that, by using this library with lite databases (such as the one downloaded
automatically in the build step), you are subject to [license terms](LICENSE-DBIP)
(requiring attribution).
## Examples
You can use `DbIpDatabase<CountryCode>` to get the actual two-letter country code. The country code database will be
embedded, in a compressed form, in your Rust binary.
```rust
use db_ip::{DbIpDatabase, CountryCode, include_country_code_database};
// Embed compressed database in binary:
let db = include_country_code_database!();
// Or, load it from the filesystem:
// let db = DbIpDatabase::<CountryCode>::from_csv_file("country_or_city_data.csv").unwrap();
assert_eq!(
db.get(&"192.99.174.0".parse().unwrap()),
Some(CountryCode::from_str("US").unwrap())
);
```
You can use `DbIpDatabase<Region>`, enabled by the `region` feature, to gain a broad understanding of an IP's location.
Since there are fewer possibilities, this takes less binary size and RAM.
```rust
use db_ip::{DbIpDatabase, Region, include_region_database};
// Embed compressed database in binary:
let db = include_region_database!();
// Or, load it from the filesystem:
// let db = DbIpDatabase::<Region>::from_csv_file("country_or_city_data.csv").unwrap();
assert_eq!(
db.get(&"192.99.174.0".parse().unwrap()),
Some(Region::NorthAmerica)
);
```
Finally, you can implement `IpData` yourself, to store any other type of data that can be derived from Country or
City data records.
## Downloading IP Geolocation Data
You can manually download the actual ip geolocation data (in CSV format) in one of the following ways.
- Use the default `download-country-lite` feature, which attempts to download the most recent available Country lite data
- [Country data lite](https://db-ip.com/db/download/ip-to-country-lite) (recommended)
- [City data lite](https://db-ip.com/db/download/ip-to-city-lite) (larger file size)
- You may also try the paid database versions for better accuracy, but they have not been tested with this crate
Once you have downloaded a CSV file, use the `csv` feature to load it.
## Features
The raw csv data takes a while to parse, even in release mode. You may use
the `serde` feature to create and load a serialized version.
You can selectively disable the `ipv4` and `ipv6` features, depending on your needs. Both are
on by default.
Lookups are relatively speedy, taking less than 100ns in release mode.
## Limitations
If you want easier access to data other than `CountryCode` and `Region`, create an issue.
The [db-ip.com](https://db-ip.com/) API is not currently supported, so it is difficult to
keep the database up to date.
## License
Code licensed under either of
* Apache License, Version 2.0
([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
* MIT license
([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
at your option.
Bundled/downloaded geolocation data licensed under [LICENSE-DBIP](LICENSE-DBIP).
## Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
dual licensed as above, without any additional terms or conditions.