searchByName static method

Future<List<Place>> searchByName({ String? query, String? street, String? city, String? county, String? state, String? country, String? postalCode, bool addressDetails = false, bool extraTags = false, bool nameDetails = false, String? language, List<String>? countryCodes, List<String>? excludePlaceIds, int limit = 10, ViewBox? viewBox, String host = 'nominatim.openstreetmap.org', })

Searches a places by their name

Use either query with a free form string or any combination of street, city, county, state, country or postalCode, but don't combine them.

When using query commas are optional, but improve search performance.

When using street you should provide it in the following format: <housenumber> <streetname>

Using addressDetails will include a breakdown of the address into elements. Default is false.

Using extraTags will include additional information in the result if available, e.g. wikipedia link, opening hours. Default is false.

Using nameDetails will include a list of alternative names in the results. These may include language variants, references, operator and brand. Default is false.

Using language will set the preferred language order for showing search results, overrides the value specified in the Accept-Language HTTP header if you are running in a browser. Either use a standard RFC2616 accept-language string or a simple comma-separated list of language codes.

Using countryCodes will limit search results to one or more countries. The country code must be the ISO 3166-1alpha2 code, e.g. gb for the United Kingdom, de for Germany.

Using excludePlaceIds will skip certain OSM objects you don't want to appear in the search results. This can be used to broaden search results. For example, if a previous query only returned a few results, then including those here would cause the search to return other, less accurate, matches (if possible).

Using limit will limit the number of returned results. Default is 10 and maximum is 50.

Using viewBox will set the preferred area to find search results and an amenity only search is allowed. In this case, give the special keyword for the amenity in square brackets, e.g. [pub].

Implementation

static Future<List<Place>> searchByName({
  String? query,
  String? street,
  String? city,
  String? county,
  String? state,
  String? country,
  String? postalCode,
  bool addressDetails = false,
  bool extraTags = false,
  bool nameDetails = false,
  String? language,
  List<String>? countryCodes,
  List<String>? excludePlaceIds,
  int limit = 10,
  ViewBox? viewBox,
  String host = 'nominatim.openstreetmap.org'
}) async {
  if (query == null) {
    assert(
      street != null ||
          city != null ||
          county != null ||
          state != null ||
          country != null ||
          postalCode != null,
      'Any search parameter is needed for a structured request',
    );
  } else {
    assert(
      street == null &&
          city == null &&
          county == null &&
          state == null &&
          country == null &&
          postalCode == null,
      'Do not use query and any other search parameter together',
    );
  }
  assert(limit > 0, 'Limit has to be greater than zero');
  assert(limit <= 50, 'Limit has to be smaller or equals than 50');
  final uri = Uri.https(
    host,
    '/search',
    {
      'format': 'jsonv2',
      if (query != null) 'q': query,
      if (street != null) 'street': street,
      if (city != null) 'city': city,
      if (county != null) 'county': county,
      if (state != null) 'state': state,
      if (country != null) 'country': country,
      if (postalCode != null) 'postalcode': postalCode,
      if (addressDetails) 'addressdetails': '1',
      if (extraTags) 'extratags': '1',
      if (nameDetails) 'namedetails': '1',
      if (language != null) 'accept-language': language,
      if (countryCodes != null && countryCodes.isNotEmpty)
        'countrycodes': countryCodes.join(','),
      if (excludePlaceIds != null && excludePlaceIds.isNotEmpty)
        'exclude_place_ids': excludePlaceIds.join(','),
      if (limit != 10) 'limit': limit.toString(),
      if (viewBox != null)
        'viewbox':
            '${viewBox.westLongitude},${viewBox.southLatitude},${viewBox.eastLongitude},${viewBox.northLatitude}',
      if (viewBox != null) 'bounded': '1',
    },
  );
  final response = await http.get(uri);
  final data = json.decode(response.body) as List<dynamic>;
  return data
      .map<Place>((p) => Place.fromJson(p as Map<String, dynamic>))
      .toList();
}