https://github.com/finnbear/db_ip
An (unofficial) Rust library for querying db-ip.com data
https://github.com/finnbear/db_ip
country-codes geolocation geolocation-database ip ipv4 ipv6 rust rust-crate rust-lang rust-library
Last synced: about 1 year ago
JSON representation
An (unofficial) Rust library for querying db-ip.com data
- Host: GitHub
- URL: https://github.com/finnbear/db_ip
- Owner: finnbear
- License: other
- Created: 2022-02-09T01:38:16.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2024-12-11T03:56:16.000Z (over 1 year ago)
- Last Synced: 2025-03-29T08:51:09.616Z (about 1 year ago)
- Topics: country-codes, geolocation, geolocation-database, ip, ipv4, ipv6, rust, rust-crate, rust-lang, rust-library
- Language: Rust
- Homepage: https://crates.io/crates/db_ip
- Size: 3.58 MB
- Stars: 7
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE-DBIP
Awesome Lists containing this project
README
# 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` 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::::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`, 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::::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.