# photon-geocoding-rs [![version](https://img.shields.io/badge/version-1.1.0-green.svg)](https://codeberg.org/vollkorntomate/photon-geocoding-rs) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0) [![crates.io](https://img.shields.io/badge/crates.io-v1.1.0-orange.svg?logo=rust)](https://crates.io/crates/photon-geocoding) An API client for Komoot's Photon API written in and for Rust. It supports forward and reverse geocoding as well as search-as-you-type. --- Get it on Codeberg The main repository is hosted on [codeberg.org](https://codeberg.org/vollkorntomate/photon-geocoding-rs). Issues and Pull Requests are preferred there, but you can still open one on GitHub. --- ## Photon Photon is a free and open-source API hosted by Komoot and powered by ElasticSearch. It returns data from the OpenStreetMap project, which is licensed under the [ODbL License](https://opendatacommons.org/licenses/odbl/). The API is available at [photon.komoot.io](https://photon.komoot.io) and licensed under the [Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0). **Important:** Please be aware of the Terms and Use of Photon! It is free to use, so please be fair and avoid excessive requests! ## Usage In your `cargo.toml`, include this: ```toml [dependencies] photon-geocoding = { version = "1.1.0" } ``` Forward geocoding: ```rust use photon_geocoding::{PhotonApiClient, PhotonFeature}; let api: PhotonApiClient = PhotonApiClient::default(); let result: Vec = api.forward_search("munich", None).unwrap(); ``` Reverse geocoding: ```rust use photon_geocoding::{PhotonApiClient, PhotonFeature}; let api: PhotonApiClient = PhotonApiClient::default(); let result: Vec = api.reverse_search(LatLon::new(48.123, 11.321), None).unwrap(); ``` Self-hosted instances (custom URL): ```rust use photon_geocoding::PhotonApiClient; let api: PhotonApiClient = PhotonApiClient::new("https://example.com"); // requests will now go to https://example.com/api and https://example.com/reverse ``` Filters: ```rust use photon_geocoding::filter::{ForwardFilter, PhotonLayer}; use photon_geocoding::{BoundingBox, LatLon, PhotonApiClient}; let api: PhotonApiClient = PhotonApiClient::default(); let filter = ForwardFilter::new() .language("FR") .bounding_box(BoundingBox { south_west: LatLon::new(40.0, 10.0), north_east: LatLon::new(50.0, 15.0), }) .layer(vec![PhotonLayer::City, PhotonLayer::State]) .additional_query(vec![("osm_tag", "!key:value")]); let results = api.forward_search("munich", Some(filter)).unwrap(); // resulting query string: "q=munich&bbox=10%2C40%2C15%2C50&lang=fr&layer=city&layer=state&osm_tag=%21key%3Avalue" ``` All requests are performed in blocking mode, so no async behavior is involved. However, the `PhotonApiClient` is thread-safe, so you can safely choose to do multiple requests in parallel using the same instance. ## Features and Bugs Feel free to open a new issue! I am always happy to improve this package. As I am fairly new to Rust, please also don't hesitate to suggest improvements on code style and/or usability (especially regarding ownership, borrowing etc.)! ## Contribution Feel free to open pull requests and help to improve this package!