{"id":19840718,"url":"https://github.com/graphhopper/geocoder-converter","last_synced_at":"2025-05-01T19:30:46.201Z","repository":{"id":43064216,"uuid":"53936001","full_name":"graphhopper/geocoder-converter","owner":"graphhopper","description":"Converts arbitrary geocoding responses to a GraphHopper response","archived":false,"fork":false,"pushed_at":"2025-02-21T13:09:33.000Z","size":225,"stargazers_count":9,"open_issues_count":10,"forks_count":13,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-04-06T17:06:40.028Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://graphhopper.com/api/1/docs/geocoding/#external-providers","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/graphhopper.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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":"2016-03-15T10:37:03.000Z","updated_at":"2025-02-21T13:09:36.000Z","dependencies_parsed_at":"2024-11-12T12:41:44.228Z","dependency_job_id":null,"html_url":"https://github.com/graphhopper/geocoder-converter","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graphhopper%2Fgeocoder-converter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graphhopper%2Fgeocoder-converter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graphhopper%2Fgeocoder-converter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graphhopper%2Fgeocoder-converter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/graphhopper","download_url":"https://codeload.github.com/graphhopper/geocoder-converter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251932583,"owners_count":21667172,"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":[],"created_at":"2024-11-12T12:27:56.330Z","updated_at":"2025-05-01T19:30:46.187Z","avatar_url":"https://github.com/graphhopper.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GraphHopper Geocoder Converter\n\nConverts a geocoding response from Nominatim, Gisgraphy, OpenCageData or NetToolKit to a GraphHopper geocoding response.\nThe geocoding converter makes it easy to request different geocoders with the same parameters and returns a similar response format.\n\nA user queries the converter and the converter then queries the geocoding provider getting the corresponding response and converting it to the GraphHopper response format:\n\n```\nsame request  format  -\u003e geocoder-converter -\u003e    a geocoding provider like photon or nominatim\nsame response format  \u003c- geocoder-converter \u003c---/\n```\n\n## Starting the Server\n\nRun the following commands from the main directory - **the version of the .jar might be different**:\n```\nmvn clean install\njava -jar target/graphhopper-geocoder-converter-0.2-SNAPSHOT.jar server converter.yml\n```\n\n### Configuring IntelliJ\n\nClick on `Run-\u003eEdit Configurations-\u003e+-\u003eApplication`\n\nMain Class: `com.graphhopper.converter.ConverterApplication`.\nProgramm Arguments: `server converter.yml`\n\n\n## API\n\nThe goal of this project is to integrate different geocoders in the [GraphHopper Geocoding API](https://graphhopper.com/api/1/docs/geocoding/).\n\nYou can select which service is used by attaching `provider=[PROVIDER_NAME]` to your geocoding query.\nAll providers provide basic geocoding functions, but all provide different features, allow to use some additional parameters, or don't support some of the parameters, or might return different values.\n\nIf a parameter is missing, please feel free to open an issue or a pull request to add it. \n    \n### Geocoding (forward)\n\nA sample geocoding query against the GraphHopper Geocoding API looks like this:\n```\nhttps://graphhopper.com/api/1/search?q=berlin\u0026key=[YOUR_KEY]\n```\n\nThis query will be translated to the following queries:\n```\nhttps://nominatim.openstreetmap.org/search?q=berlin\u0026format=json\u0026addressdetails=1\nhttps://api.opencagedata.com/geocode/v1/json?q=berlin\nhttps://services.gisgraphy.com/geocoding/search?address=berlin\u0026format=json\nhttps://api.nettoolkit.com/v1/geo/geocodes?address=berlin\n```\n\n### Reverse Geocoding\n\nA simple reverse geocoding query against the GraphHopper Geocoding API looks like this:\n```\nhttps://graphhopper.com/api/1/geocode?point=52.5487429714954,-1.81602098644987\u0026reverse=true\u0026key=[YOUR_KEY]\n```\n\nThis query will be translated to the following queries:\n```\nhttps://nominatim.openstreetmap.org/reverse?format=json\u0026lat=52.5487429714954\u0026lon=-1.81602098644987\u0026addressdetails=1\nhttps://api.opencagedata.com/geocode/v1/json?q=52.5487429714954%2C-1.81602098644987\nhttps://services.gisgraphy.com/reversegeocoding/search?format=json\u0026lat=52.5487429714954\u0026lng=-1.81602098644987\nhttps://api.nettoolkit.com/v1/geo/reverse-geocodes?latitude=52.5487429714954\u0026longitude=-1.81602098644987\n```\n\n## Providers\n\n### Nominatim \n\nYou can find out more about Nominatim [here](https://wiki.openstreetmap.org/wiki/Nominatim#Examples).\n\n**Parameters**\n\nThe geocoding converter supports the following additional Nominatim parameters, please consult the Nominatim documentation to find out detail about the parameter:\n- `viewbox`\n- `viewboxlbrt`\n- `bounded` \n- `postalcode`\n\n**Response**\n\nA sample Nominatim Response for \n```\nhttps://nominatim.openstreetmap.org/search?q=Unter%20den%20Linden%201%20Berlin\u0026format=json\u0026addressdetails=1\u0026limit=1\u0026polygon_svg=1\n```\n\nlooks like this\n```json\n{\n    \"address\": {\n        \"city\": \"Berlin\",\n        \"city_district\": \"Mitte\",\n        \"construction\": \"Unter den Linden\",\n        \"continent\": \"European Union\",\n        \"country\": \"Deutschland\",\n        \"country_code\": \"de\",\n        \"house_number\": \"1\",\n        \"neighbourhood\": \"Scheunenviertel\",\n        \"postcode\": \"10117\",\n        \"public_building\": \"Kommandantenhaus\",\n        \"state\": \"Berlin\",\n        \"suburb\": \"Mitte\"\n    },\n    \"boundingbox\": [\n        \"52.5170783996582\",\n        \"52.5173187255859\",\n        \"13.3975105285645\",\n        \"13.3981599807739\"\n    ],\n    \"class\": \"amenity\",\n    \"display_name\": \"Kommandantenhaus, 1, Unter den Linden, Scheunenviertel, Mitte, Berlin, 10117, Deutschland, European Union\",\n    \"importance\": 0.73606775332943,\n    \"lat\": \"52.51719785\",\n    \"licence\": \"Data \\u00a9 OpenStreetMap contributors, ODbL 1.0. http://www.openstreetmap.org/copyright\",\n    \"lon\": \"13.3978352028938\",\n    \"osm_id\": \"15976890\",\n    \"osm_type\": \"way\",\n    \"place_id\": \"30848715\",\n    \"svg\": \"M 13.397511 -52.517283599999999 L 13.397829400000001 -52.517299800000004 13.398131599999999 -52.517315099999998 13.398159400000001 -52.517112099999999 13.3975388 -52.517080700000001 Z\",\n    \"type\": \"public_building\"\n}\n```\n\n### OpenCageData\n\nYou can find out more about OpenCageData [here](https://geocoder.opencagedata.com/api).\n\n**Parameters**\n\nThe geocoding converter supports the following additional OCD parameters, please consult the OCD documentation to find out detail about the parameter:\n- `countrycode`\n- `bounds`\n- `nominatim` - boolean: this parameter is converted to the `only_nominatim` parameter of OCD \n- `find_osm_id` - boolean: this parameter is true by default, if you pass false this will be converted to the `no_annotations` call of OCD.\n\n**Response**\n\n~~OpenCageData responses can easily exceed 100 lines, therefore we decided not to include an example~~\n\n### Gisgraphy\n\nThe geocoding converter supports the following additional Gisgraphy parameters, please consult the Gisgraphy documentation to find out more details about the parameter: \n- `radius`: radius in meter to do search in a bounding circle\n- `country`: an iso-3166-2 country code (e.g : DE) filter the results to the specify country code\n- `autocomplete`- boolean: if true, the search is optimized for autocompletion, if false the geocoder will try to find exact matches. Autocomplete is not available for reverse queries.\n\n**Gisgraphy does not support the locale parameter**\n\n**Response**\n\nGisgraphy does not return tags from OSM and no Extent.\n\n```json\n{\n    \"id\": 5128581,\n    \"lng\": -74.00596618652344,\n    \"lat\": 40.714271545410156,\n    \"name\": \"New York City\",\n    \"zipCode\": \"10001\",\n    \"city\": \"New York City\",\n    \"state\": \"New York\",\n    \"countryCode\": \"US\",\n    \"geocodingLevel\": \"CITY\",\n    \"adm1Name\": \"New York\",\n    \"adm2Name\": \"New York City\",\n    \"adm3Name\": \"New York County\",\n    \"formatedFull\": \"New York City, New York County, New York City, New York (NY)\",\n    \"formatedPostal\": \"New York City, 10001\",\n    \"score\": 97.7906,\n    \"sourceId\": 175905\n}\n```\n### NetToolKit\n\nNetToolKit Geo provides rooftop accuracy for most US addresses, and provides a wrapper around Nominatim for other addresses. You can find out more about NetToolKit [here](https://www.nettoolkit.com/geo/about).\n\nThe geocoding converter supports the following additional NetToolKit parameters, please consult the NetToolKit documentation to find out more details about the parameter: \n- `source`: User can choose which source provider to geocode the address, this value is \"NetToolKit\" by default\n- `country_code`: an iso-3166-2 country code (e.g : US) filter the results to the specify country code\n\n**NetToolKit does not support the locale parameter**\n\n**Response**\n\nNetToolKit does not return OSM tags (e.g. osm_id, osm_type, osm_value).\n\n```json\n{\n  \"code\": 1000,\n  \"query\": {\n    \"address_query\": \"790 E Duane Ave, Sunnyvale, CA 94085\"\n  },\n  \"results\": [\n    {\n      \"address\": \"790 E Duane Avenue, Sunnyvale, CA, 94085, USA\",\n      \"latitude\": 37.3865321,\n      \"longitude\": -122.01121455,\n      \"house_number\": \"790\",\n      \"street\": \"E Duane Avenue\",\n      \"street_name\": \"Duane\",\n      \"street_type\": \"Avenue\",\n      \"city\": \"Sunnyvale\",\n      \"county\": \"Santa Clara\",\n      \"state\": \"California\",\n      \"state_code\": \"CA\",\n      \"country\": \"United States of America\",\n      \"postcode\": \"94085\",\n      \"postal_code\": \"94085\",\n      \"precision\": \"rooftop\",\n      \"provider\": \"OpenAddresses\",\n      \"ntk_geocode_time\": 664\n    }\n  ]\n}\n```\n\n### Photon\n\nPhoton offers the additional parameters:\n- `bbox`: Allows to filter for the results by a bbox using `minLon,minLat,maxLon,maxLat`, for example - `bbox=9.5,51.5,11.5,53.5`\n- `location_bias_scale`: You can define how strong the bias of the provided lat,lon is on the returned results. Range is 0.1 to 10, default is 1.6. \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgraphhopper%2Fgeocoder-converter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgraphhopper%2Fgeocoder-converter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgraphhopper%2Fgeocoder-converter/lists"}