{"id":13553178,"url":"https://github.com/komoot/photon","last_synced_at":"2026-02-11T17:07:29.531Z","repository":{"id":37484535,"uuid":"12247534","full_name":"komoot/photon","owner":"komoot","description":"an open source geocoder for openstreetmap data","archived":false,"fork":false,"pushed_at":"2024-10-29T09:14:36.000Z","size":10833,"stargazers_count":1935,"open_issues_count":69,"forks_count":285,"subscribers_count":72,"default_branch":"master","last_synced_at":"2024-10-29T10:05:05.289Z","etag":null,"topics":["elasticsearch","geocoder","geocoding","java","openstreetmap","photon","reverse-geocoding","search"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/komoot.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-08-20T16:06:16.000Z","updated_at":"2024-10-29T09:14:20.000Z","dependencies_parsed_at":"2022-07-10T04:17:06.141Z","dependency_job_id":"12a70511-d441-4fe9-9f07-ecf86f7a6339","html_url":"https://github.com/komoot/photon","commit_stats":{"total_commits":1028,"total_committers":61,"mean_commits":"16.852459016393443","dds":0.7169260700389105,"last_synced_commit":"f55d1df629470da1af593267b981a222ab1a16b0"},"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/komoot%2Fphoton","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/komoot%2Fphoton/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/komoot%2Fphoton/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/komoot%2Fphoton/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/komoot","download_url":"https://codeload.github.com/komoot/photon/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248288362,"owners_count":21078903,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["elasticsearch","geocoder","geocoding","java","openstreetmap","photon","reverse-geocoding","search"],"created_at":"2024-08-01T12:02:19.048Z","updated_at":"2026-02-11T17:07:29.526Z","avatar_url":"https://github.com/komoot.png","language":"Java","readme":"# About photon\n\n[![Continuous Integration](https://github.com/komoot/photon/workflows/CI/badge.svg)](https://github.com/komoot/photon/actions)\n\n_photon_ is an open source geocoder built for\n[OpenStreetMap](https://openstreetmap.org) data. It is based on\n[elasticsearch](http://elasticsearch.org/)/[OpenSearch](https://opensearch.org/) -\nan efficient, powerful and highly scalable search platform.\n\n_photon_ was started by [komoot](http://www.komoot.de) who also provide the\npublic demo server at [photon.komoot.io](https://photon.komoot.io).\n\n## Features\n\n- high performance\n- highly scalability\n- search-as-you-type\n- multilingual search\n- location bias\n- typo tolerance\n- filter by osm tag and value\n- filter by bounding box\n- reverse geocode a coordinate to an address\n- OSM data import (built upon [Nominatim](https://nominatim.org)) inclusive continuous updates\n- import and export dumps in concatenated JSON format\n\n## Demo server\n\nYou can try out photon via the demo server at\n[https://photon.komoot.io](http://photon.komoot.io). You are welcome to use\nthe API for your project as long as the number of requests stay in a reasonable\nlimit. Extensive usage will be throttled or completely banned. We do not\ngive guarantees for availability and reserve the right to implement changes\nwithout notice.\n\n*If you have a larger number of requests to make, please consider setting up\nyour own private instance. It is as simple as downloading two files and starting\nthe server. See instructions below.*\n\n## Installation\n\n### Requirements\n\nphoton requires Java, version 21+.\n\nIf you want to run against an external database instead of using the embedded\nserver, OpenSearch 3.x is needed.\n\nA planet-wide database requires about 95GB disk space (as of 2026, grows by\nabout 10% a year). Using SSDs for storage is strongly recommended, NVME would\neven be better. At least 64GB RAM are recommended for smooth operations, more,\nif the server takes significant load. Running photon with less RAM is possible\nbut consider increasing the available heap (using `java -Xmx8G -jar ...` for\nexample). Be careful to make sure that there remains enough free RAM that the\nsystem doesn't start swapping.\n\nIf you want to import data from Nominatim, there are additional\n[requirements for Nominatim](https://nominatim.org/release-docs/latest/admin/Installation/#prerequisites).\n\n### Setting photon up with the release binaries and extracts\n\nThis is the easiest way to set up a self-hosted photon instance.\nPre-built jar files can be downloaded from the\n[Github release page](https://github.com/komoot/photon/releases/latest).\n\n[GraphHopper](https://www.graphhopper.com/) kindly provides weekly updated\ndumps of the photon database at\n[https://download1.graphhopper.com/public](https://download1.graphhopper.com/public).\nThe dumps are available for the world-wide dataset and for selected country datasets.\nThe dumps contain names in English, German, French and local language. There\nis no support for\n[full geometry output](https://github.com/komoot/photon/pull/823). If you need\nthis feature, you need to import your own database from a JSON dump.\n\nFollow the instruction on the webpage to find the right dump suitable for\nyour version.\n\nMake sure you have bzip2 or pbzip2 installed. Do not use WinRAR for unpacking,\nit is known to have issues with the files. Execute one of these two\ncommands in your shell to download, uncompress and extract the huge\ndatabase in one step:\n\n```\nwget -O - https://download1.graphhopper.com/public/photon-db-planet-1.0-latest.tar.bz2 | bzip2 -cd | tar x\n# you can significantly speed up extracting using pbzip2 (recommended):\nwget -O - https://download1.graphhopper.com/public/photon-db-planet-1.0-latest.tar.bz2 | pbzip2 -cd | tar x\n```\n\nDon't forget to adapt the directory to **match your photon version**.\n\n#### Updating photon with a new version of the database dump\n\nWhen you want to update your local database with a newer version of the\ndatabase dump, then you need to swap out the databases atomically:\n\n* download and unpack the new version\n* swap the directories to put the new directory in place of the old one\n* restart photon and make sure everything works as expected\n* delete the old database\n\nThis unfortunately means you need twice the space of the database for updates.\n\n_WARNING: Never unpack the database in place of the old one. This will lead\nto corrupted data._\n\n\n## Usage\n\nChange to the directory where the `photon_data` database directory is located\n(aka the parent directory of `photon_data`). Then start photon with the\nfollowing command:\n\n```\njava -jar photon-*.jar\n```\n\nThe webserver is then available at `http://localhost:2322`.\n\nFor a full documentation of the usage, including on how to import and\nupdate a database, see the [Usage documentation](docs/usage.md).\n\n\n## Photon API\n\nA full description of the Photon API and results can be found in the\n[API documentation](docs/api-v1.md).\n\n## Building photon from scratch\n\nphoton uses gradle for building. To build the package from source make\nsure you have a JDK installed. Then run:\n\n```\n./gradlew build\n```\n\nThis will build and test photon. The final jar can be found in the `target` directory.\n\n\n## Contributing\n\nCode contributions and bug reports are welcome.\n\nPRs that include AI-generated content, may that be in code, in the PR\ndescription or in documentation need to\n\n1. clearly mark the AI-generated sections as such, for example, by\n   mentioning all use of AI in the PR description, and\n2. include proof that you have run the generated code on an actual\n   installation of photon. Adding and executing tests will not be\n   sufficient. You need to show that the code actually solves the problem\n   the PR claims to solve.\n\nFor questions please either use [Github discussions](https://github.com/komoot/photon/discussions)\nor join the [OpenStreetMap forum](https://community.openstreetmap.org/).\n\n## License\n\nphoton is open source and licensed under [Apache License, Version 2.0](https://opensource.org/licenses/Apache-2.0)\n\n## Related Projects\n\n- photon's search configuration was developed with a specific test framework. It is written in Python and [hosted separately](https://github.com/yohanboniface/osm-geocoding-tester).\n- There is a [leaflet-plugin](https://github.com/komoot/leaflet.photon) for displaying a search box with a photon server in the backend.\n","funding_links":[],"categories":["Java","Geographic search \u0026 routing System","java","Geospatial Library"],"sub_categories":["Java"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkomoot%2Fphoton","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkomoot%2Fphoton","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkomoot%2Fphoton/lists"}