import collections.abc from functools import partial from urllib.parse import quote, urlencode from geopy.exc import ( GeocoderAuthenticationFailure, GeocoderInsufficientPrivileges, GeocoderRateLimited, GeocoderServiceError, GeocoderUnavailable, ) from geopy.geocoders.base import DEFAULT_SENTINEL, Geocoder from geopy.location import Location from geopy.util import join_filter, logger __all__ = ("Bing", ) class Bing(Geocoder): """Geocoder using the Bing Maps Locations API. Documentation at: https://msdn.microsoft.com/en-us/library/ff701715.aspx """ structured_query_params = { 'addressLine', 'locality', 'adminDistrict', 'countryRegion', 'postalCode', } geocode_path = '/REST/v1/Locations' reverse_path = '/REST/v1/Locations/%(point)s' def __init__( self, api_key, *, scheme=None, timeout=DEFAULT_SENTINEL, proxies=DEFAULT_SENTINEL, user_agent=None, ssl_context=DEFAULT_SENTINEL, adapter_factory=None ): """ :param str api_key: Should be a valid Bing Maps API key (https://www.microsoft.com/en-us/maps/create-a-bing-maps-key). :param str scheme: See :attr:`geopy.geocoders.options.default_scheme`. :param int timeout: See :attr:`geopy.geocoders.options.default_timeout`. :param dict proxies: See :attr:`geopy.geocoders.options.default_proxies`. :param str user_agent: See :attr:`geopy.geocoders.options.default_user_agent`. :type ssl_context: :class:`ssl.SSLContext` :param ssl_context: See :attr:`geopy.geocoders.options.default_ssl_context`. :param callable adapter_factory: See :attr:`geopy.geocoders.options.default_adapter_factory`. .. versionadded:: 2.0 """ super().__init__( scheme=scheme, timeout=timeout, proxies=proxies, user_agent=user_agent, ssl_context=ssl_context, adapter_factory=adapter_factory, ) self.api_key = api_key domain = 'dev.virtualearth.net' self.geocode_api = '%s://%s%s' % (self.scheme, domain, self.geocode_path) self.reverse_api = '%s://%s%s' % (self.scheme, domain, self.reverse_path) def geocode( self, query, *, exactly_one=True, user_location=None, timeout=DEFAULT_SENTINEL, culture=None, include_neighborhood=None, include_country_code=False ): """ Return a location point by address. :param query: The address or query you wish to geocode. For a structured query, provide a dictionary whose keys are one of: `addressLine`, `locality` (city), `adminDistrict` (state), `countryRegion`, or `postalCode`. :type query: str or dict :param bool exactly_one: Return one result or a list of results, if available. :param user_location: Prioritize results closer to this location. :type user_location: :class:`geopy.point.Point` :param int timeout: Time, in seconds, to wait for the geocoding service to respond before raising a :class:`geopy.exc.GeocoderTimedOut` exception. Set this only if you wish to override, on this call only, the value set during the geocoder's initialization. :param str culture: Affects the language of the response, must be a two-letter country code. :param bool include_neighborhood: Sets whether to include the neighborhood field in the response. :param bool include_country_code: Sets whether to include the two-letter ISO code of the country in the response (field name 'countryRegionIso2'). :rtype: ``None``, :class:`geopy.location.Location` or a list of them, if ``exactly_one=False``. """ if isinstance(query, collections.abc.Mapping): params = { key: val for key, val in query.items() if key in self.structured_query_params } params['key'] = self.api_key else: params = { 'query': query, 'key': self.api_key } if user_location: params['userLocation'] = ",".join( (str(user_location.latitude), str(user_location.longitude)) ) if exactly_one: params['maxResults'] = 1 if culture: params['culture'] = culture if include_neighborhood is not None: params['includeNeighborhood'] = include_neighborhood if include_country_code: params['include'] = 'ciso2' # the only acceptable value url = "?".join((self.geocode_api, urlencode(params))) logger.debug("%s.geocode: %s", self.__class__.__name__, url) callback = partial(self._parse_json, exactly_one=exactly_one) return self._call_geocoder(url, callback, timeout=timeout) def reverse( self, query, *, exactly_one=True, timeout=DEFAULT_SENTINEL, culture=None, include_country_code=False ): """ Return an address by location point. :param query: The coordinates for which you wish to obtain the closest human-readable addresses. :type query: :class:`geopy.point.Point`, list or tuple of ``(latitude, longitude)``, or string as ``"%(latitude)s, %(longitude)s"``. :param bool exactly_one: Return one result or a list of results, if available. :param int timeout: Time, in seconds, to wait for the geocoding service to respond before raising a :class:`geopy.exc.GeocoderTimedOut` exception. Set this only if you wish to override, on this call only, the value set during the geocoder's initialization. :param str culture: Affects the language of the response, must be a two-letter country code. :param bool include_country_code: Sets whether to include the two-letter ISO code of the country in the response (field name 'countryRegionIso2'). :rtype: ``None``, :class:`geopy.location.Location` or a list of them, if ``exactly_one=False``. """ point = self._coerce_point_to_string(query) params = {'key': self.api_key} if culture: params['culture'] = culture if include_country_code: params['include'] = 'ciso2' # the only acceptable value quoted_point = quote(point.encode('utf-8')) url = "?".join((self.reverse_api % dict(point=quoted_point), urlencode(params))) logger.debug("%s.reverse: %s", self.__class__.__name__, url) callback = partial(self._parse_json, exactly_one=exactly_one) return self._call_geocoder(url, callback, timeout=timeout) def _parse_json(self, doc, exactly_one=True): """ Parse a location name, latitude, and longitude from an JSON response. """ status_code = doc.get("statusCode", 200) if status_code != 200: err = doc.get("errorDetails", "") if status_code == 401: raise GeocoderAuthenticationFailure(err) elif status_code == 403: raise GeocoderInsufficientPrivileges(err) elif status_code == 429: raise GeocoderRateLimited(err) elif status_code == 503: raise GeocoderUnavailable(err) else: raise GeocoderServiceError(err) resources = doc['resourceSets'][0]['resources'] if resources is None or not len(resources): return None def parse_resource(resource): """ Parse each return object. """ stripchars = ", \n" addr = resource['address'] address = addr.get('addressLine', '').strip(stripchars) city = addr.get('locality', '').strip(stripchars) state = addr.get('adminDistrict', '').strip(stripchars) zipcode = addr.get('postalCode', '').strip(stripchars) country = addr.get('countryRegion', '').strip(stripchars) city_state = join_filter(", ", [city, state]) place = join_filter(" ", [city_state, zipcode]) location = join_filter(", ", [address, place, country]) latitude = resource['point']['coordinates'][0] or None longitude = resource['point']['coordinates'][1] or None if latitude and longitude: latitude = float(latitude) longitude = float(longitude) return Location(location, (latitude, longitude), resource) if exactly_one: return parse_resource(resources[0]) else: return [parse_resource(resource) for resource in resources]