This information is referenced in the "Managing Your Apps. App Settings: Map Provider" article.
Geocoding of Records and Usage Basics
Geocoding takes the description of a place - such as a location's latitude/longitude coordinates or its address - and maps it to a real location on the earth's surface.
In order to display Address field values on a Map view or search Address field values with the "is near (a zip code)" filter, the Address field setting "Geocode Records" must be enabled. "is near (a zip code)" filters can be used in the following locations within Knack: formula field filters, view Data Source filters, view filter menus, or rule criteria (tasks, emails, record rules, action links).
If Address field values are to be used for display only on a record or view, there's no need to geocode them.
In Knack we calculate the shortest distance between two points based on their longitude and latitude coordinates. However when viewing maps such as HERE maps or Google maps outside of Knack they calculate the shortest "route" or mileage between the two locations accounting for driving between two points.
Map Provider Settings
Knack uses HERE Maps to display maps and geocode Address field values. This setting can be found on the App Settings > Map Provider page.
View Map Usage
The "View Map Usage" button can help you see the totals of your map view loads and geocoding usage from address fields in records, as well as the source of these counts.
Map View Loads
Each time a map view is loaded in a browser, this counts as a load. The number provided is the monthly average map view loads over the lifetime of the app, as of the current date.
Geocoding of Records
The number of Address fields on an object, where "Geocode Records" is enabled, is multiplied by the number of records in that object make up each object's "Total Count" number in the "View Map Usage" modal. The total shown ("Estimated number of monthly geocode requests") is the sum of that "Total Count" number for each object.
Note: The loading of map views and geocoding of Address field values via HERE Maps is included for Pro and above plans. You can also use Google as your provider by adding your own API key; details can be found in "Using Google Maps as the Map Provider" section below.
HERE Maps geocodes addresses to a precision of 5 decimal places.
Partial searches (street address only, city only, or ZIP code only) are not supported in HERE maps. Guidance is provided for customers during map searches if no results are returned stating: "No results for that search. Please try again with additional address data (eg. street, city, state, zip, or country).”
Custom map pins are not currently available with Knack's implementation of HERE Maps. If you'd like to keep your current code for customized map pins you'll need to choose Google Maps as the map provider.
The confirm HERE Maps update will warn you before switching:
Using Google Maps as the Map Provider
You can also use Google as your map provider by adding your own API key. In choosing Google as your map provider, you'll be responsible you will be responsible for paying Google for any usage beyond their free plan for your geocoding of records, map views and address autocomplete usage. Details on estimating costs is found below.
Additional Options Available with Google Maps
- Google Maps provides 7 decimal places of precision for geocoding.
- Google Maps can provide search results on street address only, city only, and ZIP code only.
Estimating your Google Maps spend
You can use the "View Map Usage" button to help you see the totals of your map view loads and geocoding usage from address fields in records, as well as the source of these counts.
To calculate your estimated monthly spend with Google Maps API Key use, follow the below instructions:
- Open the Google Maps Pricing Calculator
- Click "View Maps Usage" button to open the Knack "View Maps Usage" modal
- Under "Map Loads" in the Knack "View Maps Usage" modal, copy that number and paste into the Google Maps Pricing Calculator Maps > Dynamic Maps input
- Under "Geocoding Records" in the Knack "View Maps Usage" modal, copy that number and paste it into the Google Maps Pricing Calculator Places > Geocoding input
- The total on the pricing calculator provides an estimated spend based on the the last month's map views and geocoding usage in your Knack app. Note that these totals are per app.
- Also note that as Address Autocomplete requests go directly to Google, it's not currently possible to provide an estimate of an app's use of this feature. Use of this feature while using your own Google Maps API key will incur any usage charges required by Google.
Set up your Google Maps API credentials
In your Google Developer account > Menu hamburger > Billing > add billing information.
Enable APIs & get credential to use in Knack
- Create a new project in your Google developer account. There will not be any APIs enabled > click "API Library" link.
- These APIs are all managed through the API Library. Start with the"Geocoding API" and click “enable”.
- Now you need to set up a Credential to support these APIs. Go to the menu hamburger in the top left > APIs & services > Credentials.
- Create an API key > Close. Then you can use this new key in Knack.
On the Knack side, simply enter your Google Maps "API Key" and click Save Settings.
You can use the same key for multiple apps. This will bill all usage from any apps to that same Credential. You can create multiple Credentials though as well, if you want to see usage from particular Knack apps to particular Credentials.
Note: Switching to Google Maps as the map provider will geocode all address fields at that time and every 30 days after that date.
Google Maps Platform Billing
When viewing your Google Maps Platform billing, you'll see the charges outlined by Product and SKU. Below you'll find the charges that will originate from maps use in Knack.
- Geocoding API. Under the Places product = Geocoding API (Product) / Geocoding (SKU)
- Places API. Under the Places product > Places API (Product) / Autocomplete - Per Request (SKU)
Google Maps Notes & Troubleshooting
- If you'd like to test using a Google Maps API key, we recommend testing with an empty app and follow the links under "Using Google as the Map Provider" to get started. To test, manually add a few records you think specifically would benefit from testing.
- Knack is not currently able to provide a pricing model that includes use of our Google Maps API Key. You must use your own.
- When enabling Google Maps APIs, Google provides a warning: ‘This key is unrestricted. Restrictions help prevent unauthorized use and quota theft.’ While this risk does exist, based on Google’s implementation requirements it is not possible to restrict a key to both a set of domains (for map loading/address autocomplete) and an IP range (for geocoding), which are both a part of maps & geolocation features in Knack.