Geocoding

A map places a row at its latitude and longitude, which most rows don't have. Register a table's address with AddGeocoding, and its rows' coordinates are filled in from their addresses as they are created and updated, by the geocoding service the portal's configuration names.

Storing geocoded results

Saving coordinates on your records is storing a geocoder's results, and providers' terms differ on that: some limit how long results may be kept, some charge for results that are stored, and some allow them to be shown only on their own maps. Power Portals Pro provides the capability only. Making sure your provider, your plan and your use of the results comply with its terms is your responsibility.

Registering an address

Accounts and contacts have a shortcut each, for their first address: its lines, city, county, state or province, postal code and country, into address1_latitude and address1_longitude.

Any other table names its columns: the street's lines, the city, the county, the state or province, the postal code and the country, each a text, choice or lookup column (the geocoder reads a choice's label and a lookup's name), and the number columns its coordinates go in.

What a registration names is checked against Dataverse as the portal starts: a column the table doesn't have, or of the wrong kind, stops it starting with a message naming the table and column. Registered twice, a table's second registration replaces its first.

What a save does

  • A create with an address is geocoded. An update is geocoded only when it changes the address: a save that sends the address again as it was, or changes only other columns, asks nobody.
  • An update carries only the columns it changes, so the address geocoded is those changes laid over the stored address.
  • The coordinates go out in the same save whether or not the user may set those columns: geocoding runs as the app user, once the user's checks have passed (see Interceptors). The stored address is read as the app too, for the geocoder, not for the user. A session Dataverse itself secures (DataverseSecurity) is the exception: it is sent to Dataverse as its user, so Dataverse's own column security still applies to the coordinates.
  • A save that sets the coordinates itself, such as a pin moved by hand, keeps its own.
  • A save is never refused for its coordinates. An address found nowhere, or one the service can't be asked about within Geocoding:Timeout (ten seconds by default), is saved without coordinates, as is an emptied one, rather than keeping the place of the address before it. A warning is logged, without the address.

Rows saved before geocoding was registered keep the coordinates they have until their address changes.

Providers

The service is set in the PowerPortalsPro:Maps:Geocoding section, apart from the provider that draws the maps: Geocoding:Provider names it, and the map's provider is used when it doesn't.

  • Azure Maps (AzureMaps): asked as the portal's own identity, as its maps are, so no key is needed. Set AzureMaps:ClientId; the identity's Azure Maps Data Reader role lets it search.
  • Esri (Esri): asked to let its results be stored, which ArcGIS charges for. Its key, in Geocoding:ApiKey, needs the geocoding privilege and must work from the server, not only from your portal's addresses as a map's key does.
  • Google (Google): a key in Geocoding:ApiKey with the Geocoding API that works from the server; a map's key, restricted to your portal's addresses, is refused.
  • OpenStreetMap (OpenStreetMap): any Nominatim server, OpenStreetMap's own unless Geocoding:Url names another, and the default when nothing names a provider. OpenStreetMap's own server is asked at most once a second, so saves at once wait their turn, and one that waits longer than Geocoding:Timeout is saved without coordinates. It also wants to know who is asking: set Geocoding:UserAgent to your portal's name and a way to contact you. Its usage policy discourages regular geocoding by an application, so use a server of your own in production.

Once an address is registered, the settings are checked as the portal starts: a provider without what it needs stops it starting with a message naming the setting.

A geocoder of your own

Register an IGeocoder to ask another service. It is given the address as its row holds it, with a one-line form from ToString(), and returns the coordinates, or none when nothing matches; throwing saves the row without coordinates.

Coordinates without geocoding

A table whose rows get their coordinates some other way registers only the columns they are in, with AddMapCoordinates, as AddGeocoding does for its own. A map of several tables then places the table's rows with ForMaps() alone.