Add /lookup specification (#7)

* add /lookup specification * compute checksum value * fix erroneous parameters
sparkfabrik · Oct 2, 2023 · 69df10b · 69df10b
1 parent 4d2b05f
commit 69df10b
Show file tree

Hide file tree

Showing 2 changed files with 168 additions and 1 deletion.
diff --git a/docs/nominatim.openapi.json b/docs/nominatim.openapi.json
@@ -299,6 +299,173 @@
                     "Search"
                 ]
             }
+        },
+        "/lookup": {
+            "get": {
+                "summary": "Query the address and other details of one or multiple OSM objects like node, way or relation.",
+                "operationId": "lookup",
+                "description": "Returns the details of an OSM object.",
+                "parameters": [
+                    {
+                        "schema": {
+                            "type": "string",
+                            "pattern": "^([RWN][0-9]+,?)+$"
+                        },
+                        "in": "query",
+                        "required": true,
+                        "name": "osm_ids",
+                        "description": "Comma-separated list of OSM ids each prefixed with its type, one of node(N), way(W) or relation(R). Up to 50 ids can be queried at the same time."
+                    },
+                    {
+                        "schema": {
+                            "type": "string",
+                            "enum": [
+                                "xml",
+                                "json",
+                                "jsonv2",
+                                "geojson",
+                                "geocodejson"
+                            ],
+                            "default": "jsonv2"
+                        },
+                        "in": "query",
+                        "name": "format",
+                        "description": "Format of response. See [Place Output Formats](https://nominatim.org/release-docs/develop/api/Output/) for details on each format."
+                    },
+                    {
+                        "schema": {
+                            "type": "string"
+                        },
+                        "in": "query",
+                        "name": "json_callback",
+                        "description": "Wrap JSON output in a callback function (JSONP) i.e. <string>(<json>). Only has an effect for JSON output formats."
+                    },
+                    {
+                        "schema": {
+                            "type": "integer",
+                            "maximum": 1,
+                            "minimum": 0
+                        },
+                        "in": "query",
+                        "name": "addressdetails",
+                        "description": "Include a breakdown of the address into elements."
+                    },
+                    {
+                        "schema": {
+                            "type": "integer",
+                            "maximum": 1,
+                            "minimum": 0
+                        },
+                        "in": "query",
+                        "name": "extratags",
+                        "description": "Include additional information in the result if available, e.g. wikipedia link, opening hours."
+                    },
+                    {
+                        "schema": {
+                            "type": "integer",
+                            "maximum": 1,
+                            "minimum": 0
+                        },
+                        "in": "query",
+                        "name": "namedetails",
+                        "description": "Include a list of alternative names in the results. These may include language variants, references, operator and brand."
+                    },
+                    {
+                        "schema": {
+                            "type": "string"
+                        },
+                        "in": "query",
+                        "name": "accept-language",
+                        "description": "Preferred language order for showing search results, overrides the value specified in the [Accept-Language HTTP header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language). Either use a standard RFC2616 accept-language string or a simple comma-separated list of language codes."
+                    },
+                    {
+                        "schema": {
+                            "type": "integer",
+                            "maximum": 1,
+                            "minimum": 0
+                        },
+                        "in": "query",
+                        "name": "polygon_geojson",
+                        "description": "Output geometry of results as a GeoJSON."
+                    },
+                    {
+                        "schema": {
+                            "type": "integer",
+                            "maximum": 1,
+                            "minimum": 0
+                        },
+                        "in": "query",
+                        "name": "polygon_kml",
+                        "description": "Output geometry of results as a KML."
+                    },
+                    {
+                        "schema": {
+                            "type": "integer",
+                            "maximum": 1,
+                            "minimum": 0
+                        },
+                        "in": "query",
+                        "name": "polygon_svg",
+                        "description": "Output geometry of results as a SVG."
+                    },
+                    {
+                        "schema": {
+                            "type": "integer",
+                            "maximum": 1,
+                            "minimum": 0
+                        },
+                        "in": "query",
+                        "name": "polygon_text",
+                        "description": "Output geometry of results as a WKT."
+                    },
+                    {
+                        "schema": {
+                            "type": "number",
+                            "minimum": 0.0
+                        },
+                        "in": "query",
+                        "name": "polygon_threshold",
+                        "description": "Return a simplified version of the output geometry. The parameter is the tolerance in degrees with which the geometry may differ from the original geometry. Topology is preserved in the result."
+                    },
+                    {
+                        "schema": {
+                            "type": "string",
+                            "format": "email"
+                        },
+                        "in": "query",
+                        "name": "email",
+                        "description": "If you are making large numbers of request please include an appropriate email address to identify your requests. See Nominatim's [Usage Policy](https://operations.osmfoundation.org/policies/nominatim/) for more details."
+                    },
+                    {
+                        "schema": {
+                            "type": "integer",
+                            "maximum": 1,
+                            "minimum": 0
+                        },
+                        "in": "query",
+                        "name": "debug",
+                        "description": "Output assorted developer debug information. Data on internals of Nominatim's Search Loop logic, and SQL queries. The output is (rough) HTML format. This overrides the specified machine readable format."
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "type": "array",
+                                    "items": {
+                                        "$ref": "#/components/schemas/Location"
+                                    }
+                                }
+                            }
+                        }
+                    }
+                },
+                "tags": [
+                    "Lookup"
+                ]
+            }
         }
     },
     "components": {

diff --git a/docs/nominatim.openapi.json.checksum b/docs/nominatim.openapi.json.checksum
@@ -1 +1 @@
-sha512-b4a3496f4737c923c16883d68c5e4fdb8ba453103c77ae17fa8cf8d8d0a2b40768b02e81cfc5147fb8fbe7730085936d7f46e73627fd55e524fba4c3050c80de
+sha512-12cc03cf46031d824faf470d0173f9f91793f4a3e3bfd1be3b51a6544b3d8e06c6886955dfb883b0e515cdb17799f16c5b7424b0e5d7bea1e43950bca0a5c2e0