Allows specifying an optional recommended viewport bounds for
displaying the geocode result (e.g. the canvas extent to zoom
to for showing the results)
This geocoder utilises the Google Maps "geocoding" API in order to geocode
strings. The Google Maps service is not publicly available, and accordingly
an API key must be first obtained from Google and specified when constructing
this class.
(The user is responsible for managing their Google Maps API key, and ensuring
that the use of this geocoder does not exceed their usage limits! Excessive use
of the Google Maps geocoder API can result in charges being applied to the API key
holder.)
This is raw underlying API only. It is intended to be exposed to QGIS users only
via plugins, and does not result in any out-of-the-box Google Maps functionality.
In order for a plugin to use it, they must do something like this:
# create a google maps geocoder
api_key = 'my api key'
coder = QgsGoogleMapsGeocoder(api_key)
# add it to the locator bar
filter = QgsGeocoderLocatorFilter('Google', 'Google', 'addr', coder, iface.mapCanvas())
iface.registerLocatorFilter(filter)
Mini FAQ:
Q: Why is this being added to core, instead of a plugin?
A: While a plugin would be perfectly acceptable if we are only targetting QGIS desktop,
the intention here is to allow this underlying, low level class to be reused outside
of QGIS desktop (e.g. on QField) with a minimal amount of duplicate effort.
This class implements the required logic to bridge a
class which implements the QgsGeocoderInterface interface to a
QgsLocatorFilter. It allows easy creation of a locator filter
from a geocoder.
E.g.
class GoogleGeocoder(QgsGeocoderInterface):
... class which implements QgsGeocoderInterface...
my_google_geocoder = GoogleGeocoder(api_key)
my_google_locator_filter = QgsGeocoderLocatorFilter('google', 'Google Maps', 'google', my_google_geocoder, iface.mapCanvas())
iface.registerLocatorFilter(my_google_locator_filter)
Note:
There's an abstract base class QgsAbstractGeocoderLocatorFilter which
lives in core. This base class has the guts of the geocoder to filter
adapter logic, but it does NOT implement the part which actually zooms
the canvas to the geocode results (because it's in core!)
This abstract base class is in place for applications like QField,
where the GUI library and QgsMapCanvas is NOT used. Those applications
can then implement their own concrete class based on QgsAbstractGeocoderLocatorFilter
with the correct logic to zoom their interface to a region. Ultimately,
a single QgsGeocoderInterface could be usable across QGIS desktop, QField,
with almost all logic shared via the common abstract adapter class.
