{"id":13548150,"url":"https://github.com/rinigus/osmscout-server","last_synced_at":"2025-04-12T15:37:19.851Z","repository":{"id":11318482,"uuid":"68546275","full_name":"rinigus/osmscout-server","owner":"rinigus","description":"Maps server providing tiles, geocoder, and router","archived":false,"fork":false,"pushed_at":"2024-10-25T17:25:09.000Z","size":67401,"stargazers_count":170,"open_issues_count":36,"forks_count":27,"subscribers_count":18,"default_branch":"master","last_synced_at":"2025-04-03T16:11:38.269Z","etag":null,"topics":["geocoder","kirigami","libpostal","linux","map","map-tiles","mapbox-gl","mapnik","maps","navigation","offline","offline-maps","openstreetmap","osm","sailfishos","ubuntu-touch","valhalla","vector-tiles"],"latest_commit_sha":null,"homepage":"https://rinigus.github.io/osmscout-server","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rinigus.png","metadata":{"files":{"readme":"README.api.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-09-18T20:44:55.000Z","updated_at":"2025-03-26T02:09:28.000Z","dependencies_parsed_at":"2023-10-15T16:25:23.491Z","dependency_job_id":"6eb87637-5e58-4fb8-80b9-d9a3f4cda5bb","html_url":"https://github.com/rinigus/osmscout-server","commit_stats":{"total_commits":1558,"total_committers":18,"mean_commits":86.55555555555556,"dds":0.09499358151476256,"last_synced_commit":"39bcb967b9dc91b88eec48366f7821708f5eecfe"},"previous_names":[],"tags_count":83,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rinigus%2Fosmscout-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rinigus%2Fosmscout-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rinigus%2Fosmscout-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rinigus%2Fosmscout-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rinigus","download_url":"https://codeload.github.com/rinigus/osmscout-server/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248590518,"owners_count":21129837,"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":["geocoder","kirigami","libpostal","linux","map","map-tiles","mapbox-gl","mapnik","maps","navigation","offline","offline-maps","openstreetmap","osm","sailfishos","ubuntu-touch","valhalla","vector-tiles"],"created_at":"2024-08-01T12:01:06.372Z","updated_at":"2025-04-12T15:37:19.813Z","avatar_url":"https://github.com/rinigus.png","language":"C++","funding_links":[],"categories":["C++","\u003ca name=\"cpp\"\u003e\u003c/a\u003eC++","linux"],"sub_categories":[],"readme":"# API and adding support for OSM Scout Server\n\n## General notes for developers\n\nThere are several aspects that became evident while developing and\nusing OSM Scout Server for providing offline solution on a mobile\nplatform, such as Sailfish OS.\n\n### Request large tiles\n\nWhen requesting rendered map tiles, its advantageous to request larger\ntiles. Each tile is rendered with an overhead that is induced by\nlabels located close to the borders. For example, current default\nsettings in Mapnik backend, add 128 pixels on each side of the\ntile. This buffer is internally multiplied by the scale of Mapnik map,\ncommonly set to 3. So, we have 384 pixels added on each side. If the\ncommon size of the tiles is requested (256x256), each tile triggers\nrendering of 1024x1024 out of which only 256x256 section is used. In\nother words, we use only 6.25% of the rendered data. By requesting\ntiles with the size 1024x1024, we bring up efficiency to 32.7%, a\nsignificant increase.\n\n### Do not use timeouts\n\nWhen using the server on mobile, one has to remember that the server\nis not rendering tiles nor performing any other calculations while the\ndevice is asleep. The server is not keeping device awake, its a job of\na client that interacts with the user and knows whether current\noperation is time-critical, as during navigation, or can be postponed,\nas when user is just browsing a map and switched off the phone. As a\nresult, using timeouts while interacting with the server is strongly\ndiscouraged. In particular, when using timeouts and the device was put\nto sleep, this can cause large number of re-submissions by a client\nleading to failure of the server to process a long accumulated queue\nof requests in reasonable time. So, its recommended not to use any\ntimeouts when using server on the device that can be put to sleep or,\nif the timeouts are needed, not to submit new requests after\nthat. Since, when client and the server are operating on the same\ndevice, network failure is not expected, such timeouts are, in\ngeneral, not needed.\n\n## Access\n\nServer provides its functionality via HTTP or D-Bus. APIs on HTTP and\nD-Bus cover different functionality. HTTP has been available from the\nbeginning and D-Bus has been added starting from version 1.9. Below,\nHTTP API is described, followed by [D-Bus API](#d-bus-api), when\nstated.\n\n\n## Default port\n\nDefault port for HTTP access is 8553 TCP and the server binds to\n127.0.0.1 providing services to local apps only. Binding and the port\ncan be changed in the configuration file manually.\n\n\n## URL schema\n\nServer provides access via GET and POST methods. Access to\nfunctionality is provided via path and query parts of URL. The path\ndetermines the module that is accessed with the query specifying\narguments. Here, order of query elements is not important.\n\nWhen using GET, set the query parameters after `?` in the form\n`variable=value` and separate the parameters by `\u0026`.\n\nWhen using POST, path must be specified as for GET method. However,\nwhen using POST, query parameters set by URL can be mixed with the\nparameters specified in the posted JSON object in the form:\n\n```json\n{\n   \"variable1\": 3,\n   \"variable2\": \"value string\"\n}\n```\n\nPOSTed JSON object keys are checked first and used, if specified,\nignoring the query settings specified in URL.\n\nIn the description of the schema below, GET form is used, unless\nspecified differently.\n\n\n## Examples\n\nSee `examples` folder for the example queries and their\nresults. Below, just the results are referenced. For corresponding\nqueries, see accompanying [README](examples/README.md).\n\n\n## Raster tiles\n\nThe server component for providing raster tiles operates using OSM convention\nwith small extensions. URL is\n\n`http://localhost:8553/v1/tile?style={style}\u0026daylight={dlight}\u0026shift={shift}\u0026scale={scale}\u0026z={z}\u0026x={x}\u0026y={y}`\n\nwhere\n\n`{style}` - style of the map, set to `default` if not specified\n\n`{dlight}` - either 0 for night or 1 for day\n\n`{shift}` - allows to change used {z} by increasing it to {z}+{shift}\n\n`{scale}` - size of a tile in pixels is {scale}*256\n\n`{z}`, `{x}`, and `{y}` are as in http://wiki.openstreetmap.org/wiki/Slippy_map_tilenames .\n\nAddition of `{scale}` and `{shift}` allows to experiment with\ndifferent tile sizes to optimize for performance and human-map\ninteraction. Note that `shift` is ignored in Mapnik backend. See Poor\nMaps settings for example.\n\nAt present, only Mapnik backend supports different styles. When using\nlibosmscout backend, `styles` parameter is ignored.\n\n\n## Mapbox GL vector tiles\n\nThe vector tiles, associated styles, fonts, and icons are provided\nvia server.\n\n### Styles, sprite\n\nFor requesting styles, use\n\n`http://localhost:8553/v1/mbgl/style?style={style}`\n\nwhere `{style}` is a style name.\n\nFonts (glyphs) are provided via\n\n`http://localhost:8553/v1/mbgl/glyphs?stack={fontstack}\u0026range={range}`\n\nwhere\n\n`{fontstack}` - requested font stack, for example `Noto Sans`\n\n`{range}` - requested range, for example `0-255`.\n\nIn the styles, corresponding setting for glyphs is\n`http://localhost:8553/v1/mbgl/glyphs?stack={fontstack}\u0026range={range}`.\n\nThe styles can use provided sprite with icons by specifying\n`http://localhost:8553/v1/mbgl/sprite` as a corresponding URL in style\ndefinition.\n\n### Tiles\n\nTiles are usually assessed through styles. If you want to design a new\nstyle, for requesting tiles, use\n\n`http://localhost:8553/v1/mbgl/tile?z={z}\u0026x={x}\u0026y={y}`\n\nwhere\n\n`{z}`, `{x}`, and `{y}` are as in\nhttp://wiki.openstreetmap.org/wiki/Slippy_map_tilenames .\n\n\n\n## Location search\n\nThere are two versions of the location search query results. The only\ndifference is in returned JSON format with the second version, in\naddition to returning the results, giving feedback on query parsing to\nthe user.\n\n### Location search: version 1\n\nThe location search is accessed by the following URL:\n\n`http://localhost:8553/v1/search?limit={limit}\u0026search={query}`\n\nwhere\n\n`{limit}` - maximal number of search results\n\n`{query}` - location and free text search\n\nResults are returned in JSON format ([example](examples/search_v1.json)).\n\n### Location search: version 2\n\nThe location search is accessed by the following URL:\n\n`http://localhost:8553/v2/search?limit={limit}\u0026search={query}`\n\nwhere meaning of the query parameters is the same as for the version\none. However, the result includes parsing feedback when geocoder-nlp\nis used, see [example](examples/search_v2.json).\n\n### Location bias, supported by versions 1 and 2\n\nOptional parameters can be used for location bias of geocoding:\n\n`lng={lng}` - longitude for reference location, must be specified for bias\n\n`lat={lat}` - latitude for reference location, must be specified for bias\n\n`zoom={zoom}` - zoom level of a map used as a basemap for showing\nsearch result. This level is used to calculate location bias reference\ndistance. This is an optional integer parameter with the default value\nof 16.\n\n`importance={importance}` - importance of location bias (range from\n0.0-1.0, 1.0 corresponding to high location bias). This is an optional\nparameter with the default value of 0.75.\n\n\n## List of available POI types\n\nList of available POI types is available via\n\n`http://localhost:8553/v1/poi_types`\n\nThe list is given as JSON array. When using geocoder-nlp as a search\nbackend, the list represents currently used aliases for the used tags.\nShortened version of the response is given as an\n[example](examples/poi_types.json).\n\n\n## POI search near a reference position or route\n\nTo find POIs within a given radius from a specified reference position\nand/or reference route, server can be accessed via `/v1/guide` path:\n\n`http://localhost:8553/v1/guide?radius={radius}\u0026limit={limit}\u0026poitype={poitype}\u0026name={name}\u0026search={search}\u0026lng={lng}\u0026lat={lat}`\n\nwhere\n\n`{limit}` - maximal number of search results\n\n`{radius}` - distance from the reference in meters\n\n`{poitype}` - POI type name\n\n`{name}` - Name of POI to search\n\n`{search}` - a query that is run to find a reference point, the first result is used\n\n`{lng}`, `{lat}` - longitude and latidude, respectively.\n\nThe reference route can be given only through POST JSON object in the form\n\n```json\n{\n  \"route_lng\": [longitude1, longitude2, longitude3, ...],\n  \"route_lat\": [latitude1, latitude2, latitude3, ...]\n}\n```\n\nGiven POI type is considered either as an alias or imported POI\ntype. Type comparison is done in a case-insensitive manner. POI types\nare formed from OSM tags in the form `tag_value`.\n\nList of the current tags and aliases, as used by geocoder-nlp, is given at\n[https://rinigus.github.io/osmscout-server/tags](https://rinigus.github.io/osmscout-server/tags).\n\nIn addition, POI can be searched by its name. For example, you could\nsearch for the restaurant by its name. This parameter is only\nsupported by Geocoder-NLP backend.\n\nIt is required, that either POI type, POI name, or the type and name\nare specified in the query.\n\nThe reference point can be given either as a query (\"Paris\") or as a\nlocation coordinates. If the both forms are given in URL, location\ncoordinates are preferred.\n\nWhen reference route is given, the search is performed along the\nroute. It can be used to find POIs along the whole route or its\nfraction. To search along a fraction of the reference route, the route\nhas to be specified as well as the reference point (via `search` or\nthe pair of `lng`, `lat`). With the reference point specified, the\nfraction is determined by finding the closest section of the route to\nthe reference point and starting search from that section. Such search\nfor a fraction of the route allows to specify the full route and the\ncurrent position to find all POIs of interest along the remaining\nroute, for example.\n\nSearch along the route is performed from its start (full route or\nfraction) and until either the number of POIs has reached the `limit`\nor the full route has been searched along. The `distance` returned for\neach POI is in this form of the search as the distance along the route\ntill the point of the first section satisfying the specified `radius`\nto the object. As such, the returned `distance` can be not till the\nclosest section of the route nor it takes into account the underlying\nroute network required to reach POI when moving along the\nroute. However, it should give a reasonable estimate for the distance\nin question.\n\nThe result is given in JSON format. It returns a JSON object with two\nkeys: `\"origin\"` (coordinates of the reference point used in the\nsearch) and `\"results\"` (array with the POIs). See\n[example](examples/guide.json) for details.\n\n\n## Routing\n\nThe current protocol (version 2) is fully used by Valhalla's backend\nand is Valhalla's API for `route` call. In part, version 2 is\nsupported, by libosmscout as well. Version 1 (`v1/route`) is used by\nlibosmscout and is described in [OLD_API](README.older_api.md).\n\n\n### Version 2: Valhalla\n\nRouting instructions calculations are only one of the several Valhalla\nAPIs that are exposed by OSM Scout Server. For description of the URL\nschema, as used by Valhalla's backend, see below in a separate\nsection. Valhalla is a recommended backend for routing and it is\nexpected that the most of the users will be using it.\n\nThis is the version that would be mainly supported in future. It uses\nValhalla's API, as described in\nhttps://github.com/valhalla/valhalla-docs/blob/master/turn-by-turn/api-reference.md\n. Please note that there is no API key in the Valhalla's component\nused by OSM Scout Server.\n\nAt present, all calls via `v2/route`, as\n`http://localhost:8553/v2/route?...` would equivalent to Valhalla\nvia `/route?...`.\n\n\n### Version 2: libosmscout\n\nWhen using libosmscout as a backend, version 2 can be used to request\nthe routes. In this case, the server would consider limited subset of\nValhalla's API. In particular, `costing` option would be used to\nselect the transportation mode (`auto`, `bicycle`, or `pedestrian`)\nwith the order of points found from `location`. The reply of the\nserver will follow Version 1 protocol with an additional flag `API version`\nset to `libosmscout V1` in the response of the server. Using\nthis flag, the client application can determine whether version 1\nprotocol response has been used.\n\n\n## Valhalla API for routing, map matching, and other services\n\nValhalla is interfaced by OSM Scout Server through Valhalla's C++ API\nand it exposes most of Valhalla's functionality via different path\ncomponents of the URL.\n\nURL schema for Valhalla's APIs is in the form\n\n`http://localhost:8553/v2/{api_name}?json={json}`\n\nwhere\n\n`{api_name}` - name of the used API, as specified below\n\n`{json}` - JSON query, as specified by the corresponding Valhalla's API.\n\nOSM Scout Server does not impose any API key to the Valhalla's\ncalls. The following Valhalla's APIs are supported (with the link given describing the API):\n\n* `route` - [routing instructions](https://github.com/valhalla/valhalla/blob/master/docs/api/turn-by-turn/api-reference.md)\n\n* `trace_attributes` - [map matching, trace attributes](https://github.com/valhalla/valhalla/blob/master/docs/api/map-matching/api-reference.md),\n  for obtaining road attributes as a result of matching the coordinate sequence, as fed from GPS device, with the road network.\n  Can be used for just in time navigation information.\n\n* `trace_route` - [map matching, trace_route](https://github.com/valhalla/valhalla/blob/master/docs/api/map-matching/api-reference.md),\n  for creating navigation instructions on the basis of coordinate sequence. Can be used to share the used road.\n\n* `locate` - [information about streets and intersections](https://github.com/valhalla/valhalla/blob/master/docs/api/locate/api-reference.md)\n\n* `matrix` - [time-distance matrix](https://github.com/valhalla/valhalla/blob/master/docs/api/matrix/api-reference.md)\n\n* `optimized_route` - [optimized route between set of locations](https://github.com/valhalla/valhalla/blob/master/docs/api/optimized/api-reference.md)\n\n* `isochrone` - [reachability from a given point within a time limit](https://github.com/valhalla/valhalla/blob/master/docs/api/isochrone/api-reference.md)\n\n* `height` - [elevation data for a single location or a path](https://github.com/valhalla/valhalla/blob/master/docs/api/elevation/api-reference.md)\n\nAt the moment of writing (Jul 2018), elevation data is not imported in the distributed maps. The corresponding issue has been\nopened (https://github.com/rinigus/osmscout-server/issues/244).\n\n\n## Activation URL\n\nWhen its needed to start the server that has been configured for\nautostarting using systemd socket activation, there is a convenience\naccess path that will not trigger any error or further action\n\n`http://localhost:8553/v1/activate`\n\nWhen successful, it will return `{ \"status\": \"active\" }` as a\nresponse.\n\n\n## D-Bus API\n\nD-Bus API is provided via service `io.github.rinigus.OSMScoutServer`. At present,\nits used to provide map matching service for just in time navigation\ninformation. In future, D-Bus API can be extended on request.\n\n### Root\n\nAt path `/io/github/rinigus/OSMScoutServer`, interface `io.github.rinigus.OSMScoutServer`,\ncurrently the following is supported:\n\n**`Url`** string property with the URL base that can be used to\ngenerate url's for access via HTTP API. For example, by default, its\n`http://127.0.0.1:8553`.\n\nThere is also an API for D-Bus activation on at the root location. \n\n### Map matching via D-Bus\n\nD-Bus API is available only if Valhalla router is used, as configured\nby default.\n\nFor QML applications, there is a reference implementation that uses\nmap matching API to provide just in time information. The\nimplementation is available as a [QML\nPositionSourceMapMatched](https://github.com/rinigus/positionsource-mapmatched-qml)\ntype and can be easily incorporated into application without\nconsulting OSM Scout Server API.\n\nMap matching is provided at path\n`/io/github/rinigus/OSMScoutServer/mapmatching`, interface\n`io.github.rinigus.OSMScoutServer.mapmatching`. On presence of the\nservice, there is a boolean property `Active` which equals to `True`.\n\nThe main interaction with the server occurs via the following method:\n\n* **`Update`**`(int32 mode, Double latitude, Double longitude, Double\n  accuracy) -\u003e String`.  This is a method that should be called for\n  updating the current location, given by coordinates and\n  accuracy. Valhalla's map matching cost factor is given by `mode`\n  where it can have the following values\n\n  - 1 car, \"auto\" in Valhalla API\n  - 2 car along shorter distance, \"auto_shorter\" in Valhalla API\n  - 3 bicycle\n  - 4 bus\n  - 5 pedestrian\n\n  By repeatedly calling `Update`, OSM Scout Server builds trajectory\n  of the client and analyzes it to provide information regarding the\n  current location. The return value is given by JSON object in a\n  String form. Note that this object is filled _only_ with the\n  properties that have changed when compared to the previous call. For\n  example, if the street name is the same as during the last call, it\n  is not returned in the returned JSON object. The following\n  properties are supported:\n\n  - `direction` direction of motion along the matched street or path, in degrees [0,360] from true north;\n  - `direction_valid` equals to 1 if reported direction is valid, 0 otherwise;\n  - `latitude` matched coordinate;\n  - `longitude` matched coordinate;\n  - `street_name` matched street name, empty if no data is available or no match was found;\n  - `street_speed_assumed` car speed assumed for the matched street section in meters/second, negative if no data or no match was found;\n  - `street_speed_limit` car speed limit for the matched street section in meters/second, negative if no data or no match was found.\n\n  On request, more data can be made available, as supported by\n  Valhalla `trace_attributes` API.\n\nMap matching is a D-Bus client specific, with each client having\nseparate session (history of coordinates) for each of the used\nmodes. Histories of the different clients are kept separately.\n\nFor maintaining the history, clients can call\n\n* **`Reset`**`(int32 mode)` drop the history and start a session for\n  `mode` as new for the calling client.\n\n* **`Stop`**`(int32 mode)` and **`Stop`**`()` stop session for `mode`\n  or all modes for the calling client.\n\nSee [QML\nPositionSourceMapMatched](https://github.com/rinigus/positionsource-mapmatched-qml)\ntype for example implementation of the interaction with the server,\nincluding support for automatic start of the server via systemd socket\nactivation.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frinigus%2Fosmscout-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frinigus%2Fosmscout-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frinigus%2Fosmscout-server/lists"}