### Copy Example Configuration Source: https://github.com/komoot/photon/blob/master/website/Readme.md Copies the example configuration file to the photon directory. Adapt the copied file to your specific needs. ```bash cp config.js.example photon/config.js ``` -------------------------------- ### Run Photon Server Source: https://github.com/komoot/photon/blob/master/docs/usage.md Start a photon server with an existing database. Default address is 'http://127.0.0.1:2322'. ```shell java -jar photon.jar serve ``` -------------------------------- ### Serve Photon with Release Binaries Source: https://github.com/komoot/photon/blob/master/README.md Start the Photon server using the downloaded JAR file. The webserver will be available at http://localhost:2322. ```bash java -jar photon-*.jar serve ``` -------------------------------- ### Get Command Help Source: https://github.com/komoot/photon/blob/master/docs/usage.md Use this command to view detailed parameters for any photon command. ```shell java -jar photon.jar -h ``` -------------------------------- ### GeoJSON FeatureCollection Example Source: https://github.com/komoot/photon/blob/master/website/photon/index.html This is an example of the GeoJSON structure returned by the Photon API for a collection of features. ```JSON { "type": "FeatureCollection", "features": [ { "type": "Feature", "geometry": { "coordinates": [ 13.438596, 52.519854 ], "type": "Point" }, "properties": { "city": "Berlin", "country": "Germany", "name": "Berlin" } },{ "type": "Feature", "geometry": { "coordinates": [ 61.195088, 54.005826 ], "type": "Point" }, "properties": { "country": "Russia", "name": "Berlin", "postcode": "457130" } } ] } ``` -------------------------------- ### Download and Extract Photon Database Source: https://github.com/komoot/photon/blob/master/README.md Use these commands to download, uncompress, and extract the Photon database. Ensure bzip2 or pbzip2 is installed. Do not use WinRAR for unpacking. ```bash wget -O - https://download1.graphhopper.com/public/photon-db-planet-1.0-latest.tar.bz2 | bzip2 -cd | tar x ``` ```bash wget -O - https://download1.graphhopper.com/public/photon-db-planet-1.0-latest.tar.bz2 | pbzip2 -cd | tar x ``` -------------------------------- ### Synonym and Classification Terms Configuration Source: https://github.com/komoot/photon/blob/master/docs/synonyms.md This JSON configuration defines both simple search synonyms and descriptive terms for OSM key/value pairs. Use this file with the -synonym-file parameter when starting the Photon server. ```json { "search_synonyms": [ "first,1st", "second,2nd" ], "classification_terms": [ { "key": "aeroway", "value": "aerodrome", "terms": ["airport", "airfield"] }, { "key": "railway", "value": "station", "terms": ["station"] } ] } ``` -------------------------------- ### Continuous Update Script Source: https://github.com/komoot/photon/blob/master/docs/usage.md This script continuously updates both Nominatim and Photon using Photon's update API. Ensure Photon is started with -enable-update-api and set the NOMINATIM_DIR environment variable. ```bash export NOMINATIM_DIR=/srv/nominatim/... ./continuously_update_from_nominatim.sh ``` -------------------------------- ### Get API status Source: https://github.com/komoot/photon/blob/master/docs/api-v1.md Retrieve the current status of the Photon API, including data update information. This endpoint is useful for monitoring. ```HTTP http://localhost:2322/status ``` -------------------------------- ### Serve Website with Python3 Source: https://github.com/komoot/photon/blob/master/website/Readme.md Builds and serves the website using the make command, typically for local development. Access the site via http://localhost:5001/. ```bash make serve ``` -------------------------------- ### Initialize Photon Database for Updates Source: https://github.com/komoot/photon/blob/master/docs/usage.md Initialize the Photon database with necessary tables and triggers for tracking updates from a Nominatim source. Specify the user who will later run the updates. ```bash java -jar photon.jar update-init -import-user ``` -------------------------------- ### Build Photon from Source Source: https://github.com/komoot/photon/blob/master/README.md Use this command to build and test the Photon package from its source code. The final JAR file will be located in the 'target' directory. ```bash ./gradlew build ``` -------------------------------- ### Import Photon Database from Compressed Dump File Source: https://github.com/komoot/photon/blob/master/docs/usage.md Import the Photon database from a compressed JSONL dump file using standard input. This is useful for handling packed dump files. ```bash zstd --stdout -d photon-dump.jsonl.zst | java -jar photon.jar import -import-file - ``` -------------------------------- ### Import Data into Photon Source: https://github.com/komoot/photon/blob/master/docs/usage.md Create a new photon database from a Nominatim database or a JSON dump. This process overwrites any existing database. ```shell java -jar photon.jar import ``` -------------------------------- ### Create Index on Nominatim placex Table Source: https://github.com/komoot/photon/blob/master/docs/usage.md Manually create a required index on the placex table if the import user does not have the right to create indexes. Adapt the database name as required. ```bash psql -d nominatim -c 'CREATE INDEX ON placex(country_code)' ``` -------------------------------- ### Basic Forward Search Source: https://github.com/komoot/photon/blob/master/docs/api-v1.md Perform a simple forward search for a place by its name or address. The 'q' parameter is mandatory for this type of search. ```http http://localhost:2322/api?q=berlin ``` -------------------------------- ### Triggering Nominatim Update via API Source: https://github.com/komoot/photon/blob/master/docs/usage.md Use this command to trigger a Nominatim database update through the Photon API. Ensure the /nominatim-update endpoint is enabled. ```bash curl http://localhost:2322/nominatim-update ``` -------------------------------- ### Set PostgreSQL User Password Source: https://github.com/komoot/photon/blob/master/docs/usage.md Set a password for the database user to enable password authentication for PostgreSQL. Adapt the database name as required. ```bash psql -d nominatim -c "ALTER USER www-data WITH ENCRYPTED PASSWORD 'mysecretpassword'" ``` -------------------------------- ### Status Endpoint Source: https://github.com/komoot/photon/blob/master/docs/api-v1.md Provides a health check status of the Photon server. ```APIDOC ## GET /status ### Description Health check endpoint to verify the operational status of the Photon server. ### Method GET ### Endpoint /status ### Parameters None ### Response #### Success Response (200) - **status** (string) - Indicates the health status of the server (e.g., 'ok'). ``` -------------------------------- ### Checking Nominatim Update Status via API Source: https://github.com/komoot/photon/blob/master/docs/usage.md Check the status of an ongoing Nominatim database update using the Photon API. Returns 'BUSY' if an update is in progress, or 'OK' if ready for a new update. ```bash curl http://localhost:2322/nominatim-update/status ``` -------------------------------- ### Place Object Structure Source: https://github.com/komoot/photon/blob/master/docs/json-dump-format-0.1.0.md This JSON structure defines the fields and their expected types for a Place object. It includes identifiers, types, names, addresses, and location data. Ensure all required fields are present and adhere to the specified constraints. ```json { "place_id": ""/, "object_type": "", "object_id": , "osm_key": "", "osm_value": "", "categories": [ "", "", ... ], "address_type": "", "rank_address": , "importance": , "name": { }, "housenumber": "", "address": { }, "extra": { }, "postcode": "", "country_code": "", "centroid": [, ], "bbox": [, , , ], "geometry": { }, "addresslines": [ ,... ] } ``` -------------------------------- ### Filter results by OSM tag (key:value) Source: https://github.com/komoot/photon/blob/master/docs/api-v1.md Include places with a specific OSM tag and value. This is useful for precise searches. ```HTTP http://localhost:2322/api?q=berlin&osm_tag=tourism:museum ``` -------------------------------- ### Basic Search API Endpoint Source: https://github.com/komoot/photon/blob/master/website/photon/index.html Use this endpoint for a basic search query. Replace 'berlin' with your desired search term. ```HTTP photon.komoot.io/api/?q=berlin ``` -------------------------------- ### Search Source: https://github.com/komoot/photon/blob/master/website/photon/index.html Performs a text search for places. The 'q' parameter is required. ```APIDOC ## GET /api/ ### Description Performs a text search for places. The 'q' parameter is required. ### Method GET ### Endpoint /api/ ### Parameters #### Query Parameters - **q** (string) - Required - The search query. - **lat** (float) - Optional - Latitude to prioritize search results near a specific geo-position. - **lon** (float) - Optional - Longitude to prioritize search results near a specific geo-position. - **limit** (integer) - Optional - Limits the number of results returned. - **lang** (string) - Optional - Forces the preferred language for the results. ``` -------------------------------- ### Reverse Geocoding Source: https://github.com/komoot/photon/blob/master/docs/api-v1.md Find location descriptions for a given coordinate. The 'lat' and 'lon' parameters are mandatory. An optional 'radius' can be specified for the search area. ```http http://localhost:2322/reverse?lon=10&lat=52&radius=10 ``` -------------------------------- ### Address Line Object Structure Source: https://github.com/komoot/photon/blob/master/docs/json-dump-format-0.1.0.md Defines the structure for an address line object, used to reference preceding places in the dump file as address elements. The 'place_id' is mandatory, and 'isaddress' determines if the place is used for display. ```json { // MUST: ID of the place to be used as an address element. // A place object with the given ID MUST appear in the dump file before // it is referenced here. "place_id": "", // MUST: Display flag, when set to True, the place will also be used // when displaying the address of the place, otherwise it will be // only used as a search term. "isaddress": } ``` -------------------------------- ### Search API Endpoint with Result Limit Source: https://github.com/komoot/photon/blob/master/website/photon/index.html Control the number of search results returned by specifying a limit. Set 'limit' to your desired maximum number of results. ```HTTP photon.komoot.io/api/?q=berlin&limit=1 ``` -------------------------------- ### Deduplicate Search Results Source: https://github.com/komoot/photon/blob/master/docs/api-v1.md Control the deduplication of search results. By default, Photon attempts to merge duplicate entries representing the same real-world object. ```APIDOC ## GET /api (Deduplication Control) ### Description Controls the deduplication of search results. Setting `dedupe=0` disables this feature. ### Method GET ### Endpoint /api ### Parameters #### Query Parameters - **q** (string) - Required - The search query string. - **dedupe** (integer) - Optional - Set to `0` to disable deduplication. By default, results with the same name, postcode, and OSM value are deduplicated. ### Request Example ``` http://localhost:2322/api?q=berlin&dedupe=0 ``` ### Response #### Success Response (200) Returns a GeoJSON formatted response with search results, with deduplication applied as specified. #### Response Example ```json { "features": [ { "properties": { "name": "Berlin" }, "type": "Feature", "geometry": { "type": "Point", "coordinates": [13.3888599, 52.5170365] } } ] } ``` ``` -------------------------------- ### Filter results by OSM tag key Source: https://github.com/komoot/photon/blob/master/docs/api-v1.md Include places that have a specific OSM tag key, regardless of its value. This broadens search results. ```HTTP http://localhost:2322/api?q=berlin&osm_tag=tourism ``` -------------------------------- ### Search API Endpoint with Preferred Language Source: https://github.com/komoot/photon/blob/master/website/photon/index.html Force the API to return results in a preferred language. Use the 'lang' parameter with a valid language code (e.g., 'de' for German). ```HTTP photon.komoot.io/api/?q=berlin&lang=de ``` -------------------------------- ### JSON Object Structure Source: https://github.com/komoot/photon/blob/master/docs/json-dump-format-0.1.0.md Defines the mandatory 'type' and 'content' fields for all first-level JSON objects in a dump file. The 'type' specifies the data's nature, and 'content' holds the actual data payload. ```json { "type": "", "content": { } } ``` -------------------------------- ### Forward Search Filtered by Bounding Box Source: https://github.com/komoot/photon/blob/master/docs/api-v1.md Restrict search results to a specific geographic area using the 'bbox' parameter. The format is minLon,minLat,maxLon,maxLat. ```http http://localhost:2322/api?q=berlin&bbox=9.5,51.5,11.5,53.5 ``` -------------------------------- ### Reverse geocoding with tag filter Source: https://github.com/komoot/photon/blob/master/docs/api-v1.md Find places near a location that match a specific OSM tag. Useful for finding specific types of amenities. ```HTTP http://localhost:2322/reverse?lon=10&lat=52&osm_tag=amenity:pharmacy&limit=5 ``` -------------------------------- ### Search API Source: https://github.com/komoot/photon/blob/master/docs/api-v1.md Performs a forward search to find a place by its name and address. Supports location bias, bounding box filtering, and country code filtering. ```APIDOC ## GET /api ### Description Performs a forward search for a place based on a query term. Supports filtering by location bias, bounding box, and country code. ### Method GET ### Endpoint /api ### Parameters #### Query Parameters - **q** (string) - Optional - The term to search for. Mandatory unless filtering via include/exclude parameters. - **lat** (number) - Optional - Latitude of the focus point for location bias. - **lon** (number) - Optional - Longitude of the focus point for location bias. - **zoom** (number) - Optional - Describes the radius around the center for location bias. Default is 12. - **location_bias_scale** (number) - Optional - Describes how much prominence of a result should be taken into account. Values from 0.0 to 1.0. Default is 0.4. - **bbox** (string) - Optional - Restricts results to the given area in the format minLon,minLat,maxLon,maxLat. - **countrycode** (string) - Optional - Restricts results to the given countries (2-letter ISO 3166-1 alpha-2 code). Can be used multiple times. - **limit** (integer) - Optional - Sets the number of results to return. May return fewer results than requested. - **lang** (string) - Optional - Defines the language for results. Falls back to local language if translation not available. Defaults to Accept-Language header or server default. ### Request Example ``` http://localhost:2322/api?q=berlin&lon=10&lat=52&zoom=12&location_bias_scale=0.1 ``` ### Response #### Success Response (200) - **field1** (type) - Description ``` -------------------------------- ### CountryInfo Object Structure Source: https://github.com/komoot/photon/blob/master/docs/json-dump-format-0.1.0.md Defines the structure for CountryInfo objects, which collect country-specific data. It includes a 'country_code' and a 'name' object containing localized names. ```json { "country_code": "", "name": { } } ``` -------------------------------- ### Adjust Result Language Source: https://github.com/komoot/photon/blob/master/docs/api-v1.md Specify the desired language for the results using the 'lang' parameter. If the language is not available, the server falls back to the local language or a default. ```http http://localhost:2322/api?q=berlin&lang=it ``` -------------------------------- ### Reverse Geocoding Source: https://github.com/komoot/photon/blob/master/website/photon/index.html Performs reverse geocoding to find a place based on geographic coordinates. ```APIDOC ## GET /reverse ### Description Performs reverse geocoding to find a place based on geographic coordinates. ### Method GET ### Endpoint /reverse ### Parameters #### Query Parameters - **lon** (float) - Required - The longitude coordinate. - **lat** (float) - Required - The latitude coordinate. ``` -------------------------------- ### Set Number of Results Source: https://github.com/komoot/photon/blob/master/docs/api-v1.md Control the maximum number of results returned by the API using the 'limit' parameter. The server may return fewer results than requested. ```http http://localhost:2322/api?q=berlin&limit=2 ``` -------------------------------- ### Structured Search API Source: https://github.com/komoot/photon/blob/master/docs/api-v1.md Performs a geocoding search using structured address parts like city, street, and housenumber. Supports all parameters from the /api endpoint. ```APIDIDOC ## GET /structured ### Description Performs a geocoding search by splitting the query into address parts like city, street, and housenumber. Supports common parameters from the /api endpoint. ### Method GET ### Endpoint /structured ### Parameters #### Query Parameters - **countrycode** (string) - Optional - A valid ISO 3166-1 alpha-2 code. - **state** (string) - Optional - The state or province. - **county** (string) - Optional - The county. - **city** (string) - Optional - The city or town. - **postcode** (string) - Optional - The postal code. - **district** (string) - Optional - The city district or suburb. - **housenumber** (string) - Optional - The house number. - **street** (string) - Optional - The street name. - **q** (string) - Optional - General search term (used if other parameters are insufficient). - **lat** (number) - Optional - Latitude for location bias. - **lon** (number) - Optional - Longitude for location bias. - **zoom** (number) - Optional - Zoom level for location bias. Default is 12. - **location_bias_scale** (number) - Optional - Scale for location bias. Default is 0.4. - **bbox** (string) - Optional - Bounding box filter (minLon,minLat,maxLon,maxLat). - **limit** (integer) - Optional - Maximum number of results. - **lang** (string) - Optional - Desired language for results. ### Request Example ``` http://localhost:2322/structured?city=berlin&street=Unter%20den%20Linden&housenumber=2 ``` ### Response #### Success Response (200) - **field1** (type) - Description ``` -------------------------------- ### Reverse Geocoding API Endpoint Source: https://github.com/komoot/photon/blob/master/website/photon/index.html Perform reverse geocoding by providing longitude (lon) and latitude (lat) to find the nearest address or place. ```HTTP photon.komoot.io/reverse?lon=10&lat=52 ``` -------------------------------- ### Forward Search with Location Bias Source: https://github.com/komoot/photon/blob/master/docs/api-v1.md Bias search results towards a specific geographic location. Use 'lat' and 'lon' for the center, 'zoom' for the radius, and 'location_bias_scale' to adjust prominence influence. ```http http://localhost:2322/api?q=berlin&lon=10&lat=52&zoom=12&location_bias_scale=0.1 ``` -------------------------------- ### Reverse Geocoding API Source: https://github.com/komoot/photon/blob/master/docs/api-v1.md Performs reverse geocoding to find what is at a given coordinate. Supports a radius parameter and common parameters. ```APIDOC ## GET /reverse ### Description Performs reverse geocoding to find place information at a specified latitude and longitude. Supports an optional radius for the search area. ### Method GET ### Endpoint /reverse ### Parameters #### Query Parameters - **lat** (number) - Required - The latitude of the coordinate. - **lon** (number) - Required - The longitude of the coordinate. - **radius** (integer) - Optional - The radius in kilometers to search within (0 to 5000 km). - **limit** (integer) - Optional - Sets the number of results to return. - **lang** (string) - Optional - Defines the language for results. ### Request Example ``` http://localhost:2322/reverse?lon=10&lat=52&radius=10 ``` ### Response #### Success Response (200) - **field1** (type) - Description ``` -------------------------------- ### NominatimDumpFile Header Content Source: https://github.com/komoot/photon/blob/master/docs/json-dump-format-0.1.0.md Specifies the structure for the 'content' field of a NominatimDumpFile object. It includes essential metadata like version, generator, and data timestamp. ```json "content": { "version": "0.1.0", "generator": "", "database_version": "", "data_timestamp": "", "features": { } } ``` -------------------------------- ### Filter Search Results by Layer Source: https://github.com/komoot/photon/blob/master/docs/api-v1.md Filter search results to include only specific types of geographical layers, such as cities, streets, or districts. ```APIDOC ## GET /api (Layer Filtering) ### Description Filters search results to include only places within specified geographical layers. ### Method GET ### Endpoint /api ### Parameters #### Query Parameters - **q** (string) - Required - The search query string. - **layer** (string) - Optional - Specifies the layer(s) to filter by. Can be specified multiple times. Available layers include: `house`, `street`, `locality`, `district`, `city`, `county`, `state`, `country`, `other`. ### Request Example ``` http://localhost:2322/api?q=berlin&layer=city&layer=locality ``` ### Response #### Success Response (200) Returns a GeoJSON formatted response with features matching the query and layer filters. #### Response Example ```json { "features": [ { "properties": { "name": "Berlin", "layer": "city" }, "type": "Feature", "geometry": { "type": "Point", "coordinates": [13.3888599, 52.5170365] } } ] } ``` ``` -------------------------------- ### Structured Address Search Source: https://github.com/komoot/photon/blob/master/docs/api-v1.md Perform a targeted search by splitting the query into address components like city, street, and housenumber. Supports various address parameters and common search parameters. ```http http://localhost:2322/structured?city=berlin&street=Unter%20den%20Linden&housenumber=2 ``` -------------------------------- ### Reverse Geocoding with OSM Tag Filtering Source: https://github.com/komoot/photon/blob/master/docs/api-v1.md Perform reverse geocoding to find places near a specific location, with the ability to filter results by OSM tags. ```APIDOC ## GET /reverse ### Description Performs reverse geocoding to find places near a given longitude and latitude, with optional OSM tag filtering. ### Method GET ### Endpoint /reverse ### Parameters #### Query Parameters - **lon** (number) - Required - The longitude of the location. - **lat** (number) - Required - The latitude of the location. - **osm_tag** (string) - Optional - Filters results by OSM tags. See `/api` documentation for syntax. - **limit** (integer) - Optional - The maximum number of results to return. ### Request Example ``` http://localhost:2322/reverse?lon=10&lat=52&osm_tag=amenity:pharmacy&limit=5 ``` ### Response #### Success Response (200) Returns a GeoJSON formatted response with features matching the location and filters. #### Response Example ```json { "features": [ { "properties": { "name": "Pharmacy Example", "osm_key": "amenity", "osm_value": "pharmacy" }, "type": "Feature", "geometry": { "type": "Point", "coordinates": [10.0, 52.0] } } ] } ``` ``` -------------------------------- ### Search with OSM Tag Filtering Source: https://github.com/komoot/photon/blob/master/docs/api-v1.md Filter search results by including or excluding specific OSM tags and values. This allows for precise searching based on OpenStreetMap data properties. ```APIDOC ## GET /api ### Description Searches for places based on a query and filters results using OSM tags. ### Method GET ### Endpoint /api ### Parameters #### Query Parameters - **q** (string) - Required - The search query string. - **osm_tag** (string) - Optional - Filters results by OSM tags. Can be used in multiple ways: - `key:value` (include) - `!key:value` (exclude) - `key` (include places with tag key) - `:value` (include places with tag value) - `!key` (exclude places with tag key) - `:!value` (exclude places with tag value) ### Request Example ``` http://localhost:2322/api?q=berlin&osm_tag=tourism:museum ``` ### Response #### Success Response (200) Returns a GeoJSON formatted response with features matching the query and filters. #### Response Example ```json { "features": [ { "properties": { "name": "Berlin", "state": "Berlin", "country": "Germany", "countrycode": "DE", "osm_key": "place", "osm_value": "city", "osm_type": "N", "osm_id": 240109189 }, "type": "Feature", "geometry": { "type": "Point", "coordinates": [13.3888599, 52.5170365] } } ] } ``` ``` -------------------------------- ### Filter results by layer Source: https://github.com/komoot/photon/blob/master/docs/api-v1.md Filter search results to include only specific types of geographical layers, such as cities or streets. ```HTTP http://localhost:2322/api?q=berlin&layer=city&layer=locality ``` -------------------------------- ### Search API Endpoint with Geo Position Priority Source: https://github.com/komoot/photon/blob/master/website/photon/index.html Search for a location while prioritizing results near a specific geographic coordinate. Provide latitude (lat) and longitude (lon). ```HTTP photon.komoot.io/api/?q=berlin&lat=52.3879&lon=13.0582 ``` -------------------------------- ### Forward Search Filtered by Country Code Source: https://github.com/komoot/photon/blob/master/docs/api-v1.md Filter search results to specific countries using the 'countrycode' parameter. Multiple country codes can be provided. The format is the 2-letter ISO 3166-2 code. ```http http://localhost:2322/api?q=berlin&countrycode=DE ``` -------------------------------- ### Disable result deduplication Source: https://github.com/komoot/photon/blob/master/docs/api-v1.md Disable the automatic deduplication of results to ensure all matching objects are returned. Use when precise, unfiltered results are needed. ```HTTP http://localhost:2322/api?q=berlin&dedupe=0 ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.