src/nominatim_api/v1/format_json.py

   1 # SPDX-License-Identifier: GPL-3.0-or-later
   2 #
   3 # This file is part of Nominatim. (https://nominatim.org)
   4 #
   5 # Copyright (C) 2024 by the Nominatim developer community.
   6 # For a full list of authors see the git log.
   7 """
   8 Helper functions for output of results in json formats.
   9 """
  10 from typing import Mapping, Any, Optional, Tuple, Union
  11
  12 from ..utils.json_writer import JsonWriter
  13 from ..results import AddressLines, ReverseResults, SearchResults
  14 from . import classtypes as cl
  15
  16
  17 def _write_osm_id(out: JsonWriter, osm_object: Optional[Tuple[str, int]]) -> None:
  18     if osm_object is not None:
  19         out.keyval_not_none('osm_type', cl.OSM_TYPE_NAME.get(osm_object[0], None))\
  20            .keyval('osm_id', osm_object[1])
  21
  22
  23 def _write_typed_address(out: JsonWriter, address: Optional[AddressLines],
  24                          country_code: Optional[str]) -> None:
  25     parts = {}
  26     for line in (address or []):
  27         if line.isaddress:
  28             if line.local_name:
  29                 label = cl.get_label_tag(line.category, line.extratags,
  30                                          line.rank_address, country_code)
  31                 if label not in parts:
  32                     parts[label] = line.local_name
  33             if line.names and 'ISO3166-2' in line.names and line.admin_level:
  34                 parts[f"ISO3166-2-lvl{line.admin_level}"] = line.names['ISO3166-2']
  35
  36     for k, v in parts.items():
  37         out.keyval(k, v)
  38
  39     if country_code:
  40         out.keyval('country_code', country_code)
  41
  42
  43 def _write_geocodejson_address(out: JsonWriter,
  44                                address: Optional[AddressLines],
  45                                obj_place_id: Optional[int],
  46                                country_code: Optional[str]) -> None:
  47     extra = {}
  48     for line in (address or []):
  49         if line.isaddress and line.local_name:
  50             if line.category[1] in ('postcode', 'postal_code'):
  51                 out.keyval('postcode', line.local_name)
  52             elif line.category[1] == 'house_number':
  53                 out.keyval('housenumber', line.local_name)
  54             elif ((obj_place_id is None or obj_place_id != line.place_id)
  55                   and line.rank_address >= 4 and line.rank_address < 28):
  56                 rank_name = GEOCODEJSON_RANKS[line.rank_address]
  57                 if rank_name not in extra:
  58                     extra[rank_name] = line.local_name
  59
  60     for k, v in extra.items():
  61         out.keyval(k, v)
  62
  63     if country_code:
  64         out.keyval('country_code', country_code)
  65
  66
  67 def format_base_json(results: Union[ReverseResults, SearchResults],
  68                      options: Mapping[str, Any], simple: bool,
  69                      class_label: str) -> str:
  70     """ Return the result list as a simple json string in custom Nominatim format.
  71     """
  72     out = JsonWriter()
  73
  74     if simple:
  75         if not results:
  76             return '{"error":"Unable to geocode"}'
  77     else:
  78         out.start_array()
  79
  80     for result in results:
  81         out.start_object()\
  82              .keyval_not_none('place_id', result.place_id)\
  83              .keyval('licence', cl.OSM_ATTRIBUTION)\
  84
  85         _write_osm_id(out, result.osm_object)
  86
  87         # lat and lon must be string values
  88         out.keyval('lat', f"{result.centroid.lat:0.7f}")\
  89            .keyval('lon', f"{result.centroid.lon:0.7f}")\
  90            .keyval(class_label, result.category[0])\
  91            .keyval('type', result.category[1])\
  92            .keyval('place_rank', result.rank_search)\
  93            .keyval('importance', result.calculated_importance())\
  94            .keyval('addresstype', cl.get_label_tag(result.category, result.extratags,
  95                                                    result.rank_address,
  96                                                    result.country_code))\
  97            .keyval('name', result.locale_name or '')\
  98            .keyval('display_name', result.display_name or '')
  99
 100         if options.get('icon_base_url', None):
 101             icon = cl.ICONS.get(result.category)
 102             if icon:
 103                 out.keyval('icon', f"{options['icon_base_url']}/{icon}.p.20.png")
 104
 105         if options.get('addressdetails', False):
 106             out.key('address').start_object()
 107             _write_typed_address(out, result.address_rows, result.country_code)
 108             out.end_object().next()
 109
 110         if options.get('extratags', False):
 111             out.keyval('extratags', result.extratags)
 112
 113         if options.get('namedetails', False):
 114             out.keyval('namedetails', result.names)
 115
 116         # must be string values
 117         bbox = cl.bbox_from_result(result)
 118         out.key('boundingbox').start_array()\
 119            .value(f"{bbox.minlat:0.7f}").next()\
 120            .value(f"{bbox.maxlat:0.7f}").next()\
 121            .value(f"{bbox.minlon:0.7f}").next()\
 122            .value(f"{bbox.maxlon:0.7f}").next()\
 123            .end_array().next()
 124
 125         if result.geometry:
 126             for key in ('text', 'kml'):
 127                 out.keyval_not_none('geo' + key, result.geometry.get(key))
 128             if 'geojson' in result.geometry:
 129                 out.key('geojson').raw(result.geometry['geojson']).next()
 130             out.keyval_not_none('svg', result.geometry.get('svg'))
 131
 132         out.end_object()
 133
 134         if simple:
 135             return out()
 136
 137         out.next()
 138
 139     out.end_array()
 140
 141     return out()
 142
 143
 144 def format_base_geojson(results: Union[ReverseResults, SearchResults],
 145                         options: Mapping[str, Any],
 146                         simple: bool) -> str:
 147     """ Return the result list as a geojson string.
 148     """
 149     if not results and simple:
 150         return '{"error":"Unable to geocode"}'
 151
 152     out = JsonWriter()
 153
 154     out.start_object()\
 155        .keyval('type', 'FeatureCollection')\
 156        .keyval('licence', cl.OSM_ATTRIBUTION)\
 157        .key('features').start_array()
 158
 159     for result in results:
 160         out.start_object()\
 161              .keyval('type', 'Feature')\
 162              .key('properties').start_object()
 163
 164         out.keyval_not_none('place_id', result.place_id)
 165
 166         _write_osm_id(out, result.osm_object)
 167
 168         out.keyval('place_rank', result.rank_search)\
 169            .keyval('category', result.category[0])\
 170            .keyval('type', result.category[1])\
 171            .keyval('importance', result.calculated_importance())\
 172            .keyval('addresstype', cl.get_label_tag(result.category, result.extratags,
 173                                                    result.rank_address,
 174                                                    result.country_code))\
 175            .keyval('name', result.locale_name or '')\
 176            .keyval('display_name', result.display_name or '')
 177
 178         if options.get('addressdetails', False):
 179             out.key('address').start_object()
 180             _write_typed_address(out, result.address_rows, result.country_code)
 181             out.end_object().next()
 182
 183         if options.get('extratags', False):
 184             out.keyval('extratags', result.extratags)
 185
 186         if options.get('namedetails', False):
 187             out.keyval('namedetails', result.names)
 188
 189         out.end_object().next()  # properties
 190
 191         out.key('bbox').start_array()
 192         for coord in cl.bbox_from_result(result).coords:
 193             out.float(coord, 7).next()
 194         out.end_array().next()
 195
 196         out.key('geometry').raw(result.geometry.get('geojson')
 197                                 or result.centroid.to_geojson()).next()
 198
 199         out.end_object().next()
 200
 201     out.end_array().next().end_object()
 202
 203     return out()
 204
 205
 206 def format_base_geocodejson(results: Union[ReverseResults, SearchResults],
 207                             options: Mapping[str, Any], simple: bool) -> str:
 208     """ Return the result list as a geocodejson string.
 209     """
 210     if not results and simple:
 211         return '{"error":"Unable to geocode"}'
 212
 213     out = JsonWriter()
 214
 215     out.start_object()\
 216        .keyval('type', 'FeatureCollection')\
 217        .key('geocoding').start_object()\
 218                         .keyval('version', '0.1.0')\
 219                         .keyval('attribution', cl.OSM_ATTRIBUTION)\
 220                         .keyval('licence', 'ODbL')\
 221                         .keyval_not_none('query', options.get('query'))\
 222                         .end_object().next()\
 223        .key('features').start_array()
 224
 225     for result in results:
 226         out.start_object()\
 227              .keyval('type', 'Feature')\
 228              .key('properties').start_object()\
 229                                .key('geocoding').start_object()
 230
 231         out.keyval_not_none('place_id', result.place_id)
 232
 233         _write_osm_id(out, result.osm_object)
 234
 235         out.keyval('osm_key', result.category[0])\
 236            .keyval('osm_value', result.category[1])\
 237            .keyval('type', GEOCODEJSON_RANKS[max(3, min(28, result.rank_address))])\
 238            .keyval_not_none('accuracy', getattr(result, 'distance', None), transform=int)\
 239            .keyval('label', result.display_name or '')\
 240            .keyval_not_none('name', result.locale_name or None)\
 241
 242         if options.get('addressdetails', False):
 243             _write_geocodejson_address(out, result.address_rows, result.place_id,
 244                                        result.country_code)
 245
 246             out.key('admin').start_object()
 247             if result.address_rows:
 248                 for line in result.address_rows:
 249                     if line.isaddress and (line.admin_level or 15) < 15 and line.local_name \
 250                        and line.category[0] == 'boundary' and line.category[1] == 'administrative':
 251                         out.keyval(f"level{line.admin_level}", line.local_name)
 252             out.end_object().next()
 253
 254         if options.get('extratags', False):
 255             out.keyval('extra', result.extratags)
 256
 257         out.end_object().next().end_object().next()
 258
 259         out.key('geometry').raw(result.geometry.get('geojson')
 260                                 or result.centroid.to_geojson()).next()
 261
 262         out.end_object().next()
 263
 264     out.end_array().next().end_object()
 265
 266     return out()
 267
 268
 269 GEOCODEJSON_RANKS = {
 270     3: 'locality',
 271     4: 'country',
 272     5: 'state', 6: 'state', 7: 'state', 8: 'state', 9: 'state',
 273     10: 'county', 11: 'county', 12: 'county',
 274     13: 'city', 14: 'city', 15: 'city', 16: 'city',
 275     17: 'district', 18: 'district', 19: 'district', 20: 'district', 21: 'district',
 276     22: 'locality', 23: 'locality', 24: 'locality',
 277     25: 'street', 26: 'street', 27: 'street', 28: 'house'}