nominatim/clicmd/api.py

   1 """
   2 Subcommand definitions for API calls from the command line.
   3 """
   4 import logging
   5
   6 from nominatim.tools.exec_utils import run_api_script
   7
   8 # Do not repeat documentation of subcommand classes.
   9 # pylint: disable=C0111
  10
  11 LOG = logging.getLogger()
  12
  13 STRUCTURED_QUERY = (
  14     ('street', 'housenumber and street'),
  15     ('city', 'city, town or village'),
  16     ('county', 'county'),
  17     ('state', 'state'),
  18     ('country', 'country'),
  19     ('postalcode', 'postcode')
  20 )
  21
  22 EXTRADATA_PARAMS = (
  23     ('addressdetails', 'Include a breakdown of the address into elements'),
  24     ('extratags', ("Include additional information if available "
  25                    "(e.g. wikipedia link, opening hours)")),
  26     ('namedetails', 'Include a list of alternative names')
  27 )
  28
  29 DETAILS_SWITCHES = (
  30     ('addressdetails', 'Include a breakdown of the address into elements'),
  31     ('keywords', 'Include a list of name keywords and address keywords'),
  32     ('linkedplaces', 'Include a details of places that are linked with this one'),
  33     ('hierarchy', 'Include details of places lower in the address hierarchy'),
  34     ('group_hierarchy', 'Group the places by type'),
  35     ('polygon_geojson', 'Include geometry of result')
  36 )
  37
  38 def _add_api_output_arguments(parser):
  39     group = parser.add_argument_group('Output arguments')
  40     group.add_argument('--format', default='jsonv2',
  41                        choices=['xml', 'json', 'jsonv2', 'geojson', 'geocodejson'],
  42                        help='Format of result')
  43     for name, desc in EXTRADATA_PARAMS:
  44         group.add_argument('--' + name, action='store_true', help=desc)
  45
  46     group.add_argument('--lang', '--accept-language', metavar='LANGS',
  47                        help='Preferred language order for presenting search results')
  48     group.add_argument('--polygon-output',
  49                        choices=['geojson', 'kml', 'svg', 'text'],
  50                        help='Output geometry of results as a GeoJSON, KML, SVG or WKT')
  51     group.add_argument('--polygon-threshold', type=float, metavar='TOLERANCE',
  52                        help=("Simplify output geometry."
  53                              "Parameter is difference tolerance in degrees."))
  54
  55
  56 class APISearch:
  57     """\
  58     Execute a search query.
  59
  60     This command works exactly the same as if calling the /search endpoint on
  61     the web API. See the online documentation for more details on the
  62     various parameters:
  63     https://nominatim.org/release-docs/latest/api/Search/
  64     """
  65
  66     @staticmethod
  67     def add_args(parser):
  68         group = parser.add_argument_group('Query arguments')
  69         group.add_argument('--query',
  70                            help='Free-form query string')
  71         for name, desc in STRUCTURED_QUERY:
  72             group.add_argument('--' + name, help='Structured query: ' + desc)
  73
  74         _add_api_output_arguments(parser)
  75
  76         group = parser.add_argument_group('Result limitation')
  77         group.add_argument('--countrycodes', metavar='CC,..',
  78                            help='Limit search results to one or more countries')
  79         group.add_argument('--exclude_place_ids', metavar='ID,..',
  80                            help='List of search object to be excluded')
  81         group.add_argument('--limit', type=int,
  82                            help='Limit the number of returned results')
  83         group.add_argument('--viewbox', metavar='X1,Y1,X2,Y2',
  84                            help='Preferred area to find search results')
  85         group.add_argument('--bounded', action='store_true',
  86                            help='Strictly restrict results to viewbox area')
  87
  88         group = parser.add_argument_group('Other arguments')
  89         group.add_argument('--no-dedupe', action='store_false', dest='dedupe',
  90                            help='Do not remove duplicates from the result list')
  91
  92
  93     @staticmethod
  94     def run(args):
  95         if args.query:
  96             params = dict(q=args.query)
  97         else:
  98             params = {k: getattr(args, k) for k, _ in STRUCTURED_QUERY if getattr(args, k)}
  99
 100         for param, _ in EXTRADATA_PARAMS:
 101             if getattr(args, param):
 102                 params[param] = '1'
 103         for param in ('format', 'countrycodes', 'exclude_place_ids', 'limit', 'viewbox'):
 104             if getattr(args, param):
 105                 params[param] = getattr(args, param)
 106         if args.lang:
 107             params['accept-language'] = args.lang
 108         if args.polygon_output:
 109             params['polygon_' + args.polygon_output] = '1'
 110         if args.polygon_threshold:
 111             params['polygon_threshold'] = args.polygon_threshold
 112         if args.bounded:
 113             params['bounded'] = '1'
 114         if not args.dedupe:
 115             params['dedupe'] = '0'
 116
 117         return run_api_script('search', args.project_dir,
 118                               phpcgi_bin=args.phpcgi_path, params=params)
 119
 120 class APIReverse:
 121     """\
 122     Execute API reverse query.
 123
 124     This command works exactly the same as if calling the /reverse endpoint on
 125     the web API. See the online documentation for more details on the
 126     various parameters:
 127     https://nominatim.org/release-docs/latest/api/Reverse/
 128     """
 129
 130     @staticmethod
 131     def add_args(parser):
 132         group = parser.add_argument_group('Query arguments')
 133         group.add_argument('--lat', type=float, required=True,
 134                            help='Latitude of coordinate to look up (in WGS84)')
 135         group.add_argument('--lon', type=float, required=True,
 136                            help='Longitude of coordinate to look up (in WGS84)')
 137         group.add_argument('--zoom', type=int,
 138                            help='Level of detail required for the address')
 139
 140         _add_api_output_arguments(parser)
 141
 142
 143     @staticmethod
 144     def run(args):
 145         params = dict(lat=args.lat, lon=args.lon)
 146         if args.zoom is not None:
 147             params['zoom'] = args.zoom
 148
 149         for param, _ in EXTRADATA_PARAMS:
 150             if getattr(args, param):
 151                 params[param] = '1'
 152         if args.format:
 153             params['format'] = args.format
 154         if args.lang:
 155             params['accept-language'] = args.lang
 156         if args.polygon_output:
 157             params['polygon_' + args.polygon_output] = '1'
 158         if args.polygon_threshold:
 159             params['polygon_threshold'] = args.polygon_threshold
 160
 161         return run_api_script('reverse', args.project_dir,
 162                               phpcgi_bin=args.phpcgi_path, params=params)
 163
 164
 165 class APILookup:
 166     """\
 167     Execute API lookup query.
 168
 169     This command works exactly the same as if calling the /lookup endpoint on
 170     the web API. See the online documentation for more details on the
 171     various parameters:
 172     https://nominatim.org/release-docs/latest/api/Lookup/
 173     """
 174
 175     @staticmethod
 176     def add_args(parser):
 177         group = parser.add_argument_group('Query arguments')
 178         group.add_argument('--id', metavar='OSMID',
 179                            action='append', required=True, dest='ids',
 180                            help='OSM id to lookup in format <NRW><id> (may be repeated)')
 181
 182         _add_api_output_arguments(parser)
 183
 184
 185     @staticmethod
 186     def run(args):
 187         params = dict(osm_ids=','.join(args.ids))
 188
 189         for param, _ in EXTRADATA_PARAMS:
 190             if getattr(args, param):
 191                 params[param] = '1'
 192         if args.format:
 193             params['format'] = args.format
 194         if args.lang:
 195             params['accept-language'] = args.lang
 196         if args.polygon_output:
 197             params['polygon_' + args.polygon_output] = '1'
 198         if args.polygon_threshold:
 199             params['polygon_threshold'] = args.polygon_threshold
 200
 201         return run_api_script('lookup', args.project_dir,
 202                               phpcgi_bin=args.phpcgi_path, params=params)
 203
 204
 205 class APIDetails:
 206     """\
 207     Execute API details query.
 208
 209     This command works exactly the same as if calling the /details endpoint on
 210     the web API. See the online documentation for more details on the
 211     various parameters:
 212     https://nominatim.org/release-docs/latest/api/Details/
 213     """
 214
 215     @staticmethod
 216     def add_args(parser):
 217         group = parser.add_argument_group('Query arguments')
 218         objs = group.add_mutually_exclusive_group(required=True)
 219         objs.add_argument('--node', '-n', type=int,
 220                           help="Look up the OSM node with the given ID.")
 221         objs.add_argument('--way', '-w', type=int,
 222                           help="Look up the OSM way with the given ID.")
 223         objs.add_argument('--relation', '-r', type=int,
 224                           help="Look up the OSM relation with the given ID.")
 225         objs.add_argument('--place_id', '-p', type=int,
 226                           help='Database internal identifier of the OSM object to look up')
 227         group.add_argument('--class', dest='object_class',
 228                            help=("Class type to disambiguated multiple entries "
 229                                  "of the same object."))
 230
 231         group = parser.add_argument_group('Output arguments')
 232         for name, desc in DETAILS_SWITCHES:
 233             group.add_argument('--' + name, action='store_true', help=desc)
 234         group.add_argument('--lang', '--accept-language', metavar='LANGS',
 235                            help='Preferred language order for presenting search results')
 236
 237     @staticmethod
 238     def run(args):
 239         if args.node:
 240             params = dict(osmtype='N', osmid=args.node)
 241         elif args.way:
 242             params = dict(osmtype='W', osmid=args.node)
 243         elif args.relation:
 244             params = dict(osmtype='R', osmid=args.node)
 245         else:
 246             params = dict(place_id=args.place_id)
 247         if args.object_class:
 248             params['class'] = args.object_class
 249         for name, _ in DETAILS_SWITCHES:
 250             params[name] = '1' if getattr(args, name) else '0'
 251
 252         return run_api_script('details', args.project_dir,
 253                               phpcgi_bin=args.phpcgi_path, params=params)
 254
 255
 256 class APIStatus:
 257     """\
 258     Execute API status query.
 259
 260     This command works exactly the same as if calling the /status endpoint on
 261     the web API. See the online documentation for more details on the
 262     various parameters:
 263     https://nominatim.org/release-docs/latest/api/Status/
 264     """
 265
 266     @staticmethod
 267     def add_args(parser):
 268         group = parser.add_argument_group('API parameters')
 269         group.add_argument('--format', default='text', choices=['text', 'json'],
 270                            help='Format of result')
 271
 272     @staticmethod
 273     def run(args):
 274         return run_api_script('status', args.project_dir,
 275                               phpcgi_bin=args.phpcgi_path,
 276                               params=dict(format=args.format))