From 594f0c9cdeee6e3ce168c69d83b9590a777881ab Mon Sep 17 00:00:00 2001 From: Alessio Cimarelli Date: Mon, 2 Oct 2023 18:09:00 +0200 Subject: [PATCH] feat: change default format from `jsonv2` to `geocodejson` Define GeocodeJSON json schema for both `search` and `lookup` endpoints and clean now useless schemas. Refs: #2 --- docs/nominatim.openapi.json | 256 ++++++++++++++++++++------- docs/nominatim.openapi.json.checksum | 2 +- 2 files changed, 190 insertions(+), 68 deletions(-) diff --git a/docs/nominatim.openapi.json b/docs/nominatim.openapi.json index b083cc1..860c864 100644 --- a/docs/nominatim.openapi.json +++ b/docs/nominatim.openapi.json @@ -103,11 +103,11 @@ "geojson", "geocodejson" ], - "default": "jsonv2" + "default": "geocodejson" }, "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." + "description": "Format of response. See [Place Output Formats](https://nominatim.org/release-docs/develop/api/Output/) for details on each format. If not specified, it is equal to `jsonv2`." }, { "schema": { @@ -121,7 +121,8 @@ "schema": { "type": "integer", "maximum": 1, - "minimum": 0 + "minimum": 0, + "default": 1 }, "in": "query", "name": "addressdetails", @@ -286,10 +287,7 @@ "content": { "application/json": { "schema": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Location" - } + "$ref": "#/components/schemas/GeocodeJson" } } } @@ -326,7 +324,7 @@ "geojson", "geocodejson" ], - "default": "jsonv2" + "default": "geocodejson" }, "in": "query", "name": "format", @@ -344,7 +342,8 @@ "schema": { "type": "integer", "maximum": 1, - "minimum": 0 + "minimum": 0, + "default": 1 }, "in": "query", "name": "addressdetails", @@ -455,7 +454,7 @@ "schema": { "type": "array", "items": { - "$ref": "#/components/schemas/Location" + "$ref": "#/components/schemas/GeocodeJson" } } } @@ -470,82 +469,205 @@ }, "components": { "schemas": { - "Location": { - "title": "Location", + "BBox": { + "type": "array", + "minItems": 4, + "items": { + "type": "number" + } + }, + "GeocodeJson": { + "title": "GeocodeJSON schema", "type": "object", "properties": { - "place_id": { "type": "integer" }, - "licence": { "type": "string" }, - "osm_type": { + "type": { "type": "string", - "enum": [ "node", "way", "relation" ] + "enum": [ + "FeatureCollection" + ] + }, + "geocoding": { + "$ref": "#/components/schemas/GeocodeJsonMeta" }, - "osm_id": { "type": "integer" }, - "boundingbox": { + "features": { "type": "array", - "minItems": 4, - "maxItems": 4, - "items": { "type": "string" } - }, - "lat": { "type": "string" }, - "lon": { "type": "string" }, - "display_name": { "type": "string" }, - "place_rank": { "type": "integer" }, - "category": { "type": "string" }, - "type": { "type": "string" }, - "importance": { "type": "number" }, - "icon": { "type": "string", "format": "uri" }, - "address": { "$ref": "#/components/schemas/Address" }, - "extratags": { "$ref": "#/components/schemas/Extratags" }, - "namedetails": { "$ref": "#/components/schemas/Namedetails" } + "items": { + "$ref": "#/components/schemas/GeocodeJsonFeature" + } + }, + "bbox": { + "$ref": "#/components/schemas/BBox" + } }, "required": [ - "display_name", - "lat", - "lon" + "type", + "geocoding", + "features" ] }, - "Address": { - "title": "Address", + "GeocodeJsonMeta": { "type": "object", "properties": { - "road": { "type": "string" }, - "suburb": { "type": "string" }, - "city": { "type": "string" }, - "county": { "type": "string" }, - "ISO3166-2-lvl6": { "type": "string" }, - "state_district": { "type": "string" }, - "state": { "type": "string" }, - "ISO3166-2-lvl4": { "type": "string" }, - "postcode": { "type": "string" }, - "country": { "type": "string" }, - "country_code": { "type": "string" } - } + "version": { + "type": "string", + "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$" + }, + "licence": { + "type": "string" + }, + "attribution": { + "type": "string" + }, + "query": { + "type": "string" + } + }, + "required": [ + "version" + ] }, - "Extratags": { - "title": "Extratags", + "GeocodeJsonFeature": { "type": "object", "properties": { - "capital": { "type": "string" }, - "website": { "type": "string", "format": "uri" }, - "wikidata": { "type": "string" }, - "wikipedia": { "type": "string" }, - "population": { "type": "integer" } + "type": { + "const": "string", + "enum": "Feature" + }, + "id": { + "oneOf": [ { "type": "number" }, { "type": "string" } ] + }, + "properties": { + "type": "object", + "properties": { + "geocoding": { + "$ref": "#/components/schemas/OSMFeatureMeta" + } + }, + "required": [ + "geocoding" + ] + }, + "geometry": { + "$ref": "https://geojson.org/schema/Geometry.json" + }, + "bbox": { + "$ref": "#/components/schemas/BBox" + } + }, + "required": [ + "type", + "properties", + "geometry" + ] + }, + "OSMFeatureMeta": { + "type": "object", + "allOf": [{ "$ref": "#/components/schemas/GeocodeJsonFeatureMeta" }], + "properties": { + "osm_type": { + "type": "string", + "examples": [ + "node", + "way", + "relation" + ] + }, + "osm_id": { + "type": "integer" + }, + "osm_key": { + "type": "string", + "examples": [ + "boundary", + "highway", + "amenity" + ] + }, + "osm_value": { + "type": "string", + "examples": [ + "residential", + "restaurant" + ] + } } }, - "Namedetails": { - "title": "Namedetails", + "GeocodeJsonFeatureMeta": { "type": "object", "properties": { - "name": { "type": "string" }, - "official_name": { "type": "string" } + "type": { + "type": "string", + "examples": [ + "house", + "street", + "district", + "city", + "county", + "state", + "country", + "locality" + ] + }, + "accuracy": { + "type": "integer", + "minimum": 0 + }, + "label": { + "type": "string" + }, + "name": { + "type": "string" + }, + "housenumber": { + "type": "string" + }, + "street": { + "type": "string" + }, + "locality": { + "type": "string" + }, + "postcode": { + "type": "string" + }, + "city": { + "type": "string" + }, + "district": { + "type": "string" + }, + "county": { + "type": "string" + }, + "state": { + "type": "string" + }, + "country": { + "type": "string" + }, + "admin": { + "type": "object", + "properties": { + "level2": { "type": "string" }, + "level3": { "type": "string" }, + "level4": { "type": "string" }, + "level5": { "type": "string" }, + "level6": { "type": "string" }, + "level7": { "type": "string" }, + "level8": { "type": "string" }, + "level9": { "type": "string" }, + "level10": { "type": "string" }, + "level11": { "type": "string" } + } + }, + "geohash": { + "type": "string", + "pattern": "^[a-zA-Z0-9]+(:.+)?$" + } }, - "patternProperties": { - "^name:": { "type": "string" }, - "^old_name:": { "type": "string" }, - "^_place_name:": { "type": "string" }, - "^alt_name:": { "type": "string" } - } + "required": [ + "type" + ] } } } diff --git a/docs/nominatim.openapi.json.checksum b/docs/nominatim.openapi.json.checksum index 70ac564..3a91f57 100644 --- a/docs/nominatim.openapi.json.checksum +++ b/docs/nominatim.openapi.json.checksum @@ -1 +1 @@ -sha512-12cc03cf46031d824faf470d0173f9f91793f4a3e3bfd1be3b51a6544b3d8e06c6886955dfb883b0e515cdb17799f16c5b7424b0e5d7bea1e43950bca0a5c2e0 \ No newline at end of file +sha512-807349bad147f45bc9ae5c8753a19a7f9fa2015837d3af6a761ba2f864699ab153b5405c6db2677b673c29e992143434bf228a661f4c219f7ba909d4b2365846 \ No newline at end of file