Google Maps API Integration

Why you need a Google Maps API key (and when you must bring your own)

• Starter & Established plans: You’re covered—OctopusPro uses a shared corporate key, so you don’t need to do anything.
• Unlimited Users plan: You must use your own key. At this scale, your account can fire tens of thousands of Geocoding, Distance Matrix/Routes and Places calls each month, which would blow past the limits on our shared key, so Google requires you to run on a private key tied to your own billing account. The key lets Google authenticate the call, apply the free usage allowance/credits, and block unauthorized traffic. Without this key, you’ll see the following error:

Oops! Something went wrong.
This page didn’t load Google Maps correctly. See the JavaScript console for technical details.

March 2025 change: Google replaced the single US$200 monthly credit with free monthly buckets per SKU (API). You still need billing enabled, but each key now gets a quota of free requests per API plus automatic volume discounts after that.

What the Maps APIs do for OctopusPro
They render maps and return data for: plotting fieldworker routes, calculating travel time/arrival ETAs, converting addresses to latitude/longitude, and pulling place details for your booking forms. Without a valid key you can’t show maps or calculate distances inside OctopusPro.

---

Billing & pricing

Some OctopusPro plans (Unlimited Users) require you to open your own Google Maps billing account and key; others use ours. Either way, Google bills for Maps/Routes/Places usage—not OctopusPro. The $99 platform licence on the Unlimited Users plan is our software fee only; any Google charges are separate. Most customers still pay $0 because the new free buckets are generous and discounts kick in as you grow.

APIs that are free or don’t count against credits: Maps Embed API and the mobile SDKs (Android/iOS) currently show as no-charge SKUs.

---

How the new free tier works (example numbers)

Google’s FAQ shows fixed free request counts per SKU. In practice, that means buckets like:

API / SKU	Free events per month (illustrative)	Typical OctopusPro use
Routes API / Distance Matrix	~40,000 basic route elements	Travel-time & mileage fees
Geocoding API	~15,000 lookups	Converting service addresses to GPS
Places Autocomplete (sessioned)	~11,000 sessions	Fast address entry in booking forms

Stay under those and you pay $0; go over and pricing starts around US$0.005 per event, then drops ~20–40% in higher bands. (Exact caps & rates are in Google’s pricing tables—always check there for current numbers.)

---

Estimating your spend

1. Open Google’s interactive pricing calculator and plug in your expected monthly call counts. (Google Maps Platform)
2. Rough rule: each booking generally triggers one geocode, one autocomplete session and one distance/route call.
3. The calculator nets out free buckets and discounts, so if you’re under quota it will show $0.

---

Good to know

• Set budget alerts in Google Cloud to avoid surprises (alerts don’t cap usage; they just warn you).
• Starter/Established plans don’t need a private key; your usage rides on our pooled allowance.
• Even on Unlimited Users, most customers run free or very low cost until they hit serious scale—and tiered pricing keeps per-booking map spend tiny.

---

Before you start (one‑time setup)

(Follow these in order. Keep this page open while you work.)

1. Log in & pick a project

• Go to Google Cloud Console, sign in, and create or choose a project.
• Link a billing account to that project—keys won’t work without billing.

Yes—merge it. Put the “what/why/enable” info directly under Step 2: Turn on the right Maps APIs so readers see everything in one place. Drop the separate “APIs you can safely restrict to” section (or leave a one‑line reminder later that says “Restrict your keys to the APIs above”).

---

2. Turn on the right Maps APIs

In APIs & Services ▸ Library, search each name below and click ENABLE. Later, when you restrict your keys, select only these APIs.

• Maps JavaScript API – shows interactive maps in the browser.
• Maps Static API – creates still map images for PDFs/emails.
• Geocoding API – converts addresses ↔ GPS coordinates.
• Geolocation API – figures out a device’s approximate location.
• Distance Matrix API (or Routes API ▸ Compute Route Matrix) – travel time & distance.
• Directions API (Legacy) or Routes API ▸ Compute Routes – turn‑by‑turn routes.
• Places API (+ Places SDK for Android) – fast address/places autocomplete.
• Time Zone API – returns the correct local time zone for a location.

Don’t worry about the names—just enable this list and you’re covered.

Reminder: Use these same APIs when you apply API restrictions to your Web services, Android and iOS keys (your Web JS key stays “Don’t restrict” per our dev note).

---

3. Plan for four separate keys

You’ll create one key for each place OctopusPro calls Google: Web services, Android, Web JS, iOS. Separate keys let you lock each one down and keep any leak small.

---

Create & lock your keys

You create four separate keys in Step 4 so you can lock each one differently in Step 5. Renaming them first (“Maps – Web JS”, “Maps – Web Services”, “Maps – Android”, “Maps – iOS”) lets you instantly know which lock (restriction) to apply. Google says you are financially responsible if an unrestricted key is abused, so each key needs the right lock.

---

4. Create & name your keys (repeat this 4 times)

Path: Menu ▸ APIs & Services ▸ Credentials ▸ Create credentials ▸ API key
Immediately click Edit key and rename it to its job (e.g. “Maps API key – Android”). Don’t add locks yet—just save the name.

Create four keys first, give each a clear name, then go back into each key and add the correct locks. Naming comes first so you always know which lock set belongs to which key.

5. Lock each key (apply restrictions) — one by one

For each named key:

1. Open it → Application restriction = who can use it (domain, IP, package ID, bundle ID).
2. API restriction = what it can call (only the Maps APIs you enabled).
3. Save.
   This is the “locks on the right doors” step.

Do it because:

• It locks your Google Maps “key” to your site/app only, so strangers can’t use it.
• It limits what that key is allowed to do, so even if it leaks, the damage is tiny.
• It protects your budget—Google bills every call made with your key.
• Google themselves warn that unrestricted keys can be stolen and misused.

If you don’t:

• Anyone who finds the key (in page source) can run up your bill.
• Your monthly quota can be drained by someone else, and your maps/features can stop working for real customers.
• You’ll waste time cleaning up, rotating keys, and disputing charges after the fact.

Plain English analogy: Leaving an API key unrestricted is like leaving your credit card on a café table with the PIN written on it—people can spend your money, and your card may get blocked when the limit is hit.Lock it down once, avoid the headache forever.

---

Plug keys into OctopusPro

6. Add them in your account

Settings ▸ Developer Integrations ▸ google-api-maps → paste each key in its matching field (Web services, Android, Web JS, iOS) → Save.

---

Test & monitor

7. Check everything works

• Wait a few minutes for restrictions to propagate.
• Try a booking form, address search or route calc in OctopusPro.
• If you see “This API project is not authorized…” or RefererNotAllowedMapError, your restriction type or domain list is wrong—fix it and retry.
• In Google Cloud, open APIs & Services ▸ Metrics to watch usage spikes.

8. Rotate or fix a key if needed

• Click Regenerate key on the key detail page, update OctopusPro, then delete the old key once traffic stops.
• Error “API keys with referrer restrictions cannot be used with this API” = wrong restriction. Use None/IP for server keys, Websites for browser keys, etc.

---

Quick troubleshooting

• REQUEST_DENIED / billing error: Billing not linked or quota exceeded—check Billing.
• Maps won’t load in browser: Web JS key missing, domain not whitelisted, or key restricted to server APIs.
• Android/iOS blank maps/crash: Package name, SHA‑1 or bundle ID typo—match exactly (case-sensitive).
• No distance/ETA: Distance Matrix or Routes API not enabled for that key.
• Wrong time zone: Time Zone API not enabled.

---

APIs to enable & restrict (recap)

API name	What it powers in OctopusPro	Why you need it / benefit	What you do
Maps JavaScript API	Interactive maps in the browser (booking forms, portal)	Customers & staff can see and move around live maps	Enable it. When restricting keys, include it on server/mobile keys (Web JS key is not API‑restricted)
Maps Static API	Still map images in PDFs, emails, reports	Nice map snapshots without loading a full interactive map	Enable it. Add to restricted keys
Geocoding API	Turns an address into GPS coords (and back)	Lets OctopusPro find exact locations for jobs & invoices	Enable it. Add to restricted keys
Geolocation API	Figures out a device’s location from Wi‑Fi/cell data	Helps locate a tech or a customer when GPS/address isn’t available	Enable it. Add to restricted keys
Distance Matrix API or Routes API → Compute Route Matrix	Calculates travel time & distance between many points	Auto mileage fees, fastest tech assignment, ETA calculations	Enable one of them (whichever your console shows). Add to restricted keys
Directions API (Legacy) or Routes API → Compute Routes	Turn‑by‑turn routes between two points	Driving directions & route summaries	Enable one of them (legacy or new). Add to restricted keys
Places API (+ Places SDK for Android)	Address/place autocomplete as you type	Faster, error‑free address entry in forms	Enable it (and the SDK on Android). Add to restricted keys
Time Zone API	Returns the correct local time zone for a lat/long	Accurate local times on bookings & reminders	Enable it. Add to restricted keys

If Google shows the newer Routes API screens instead of “Distance Matrix” or “Directions,” just enable the Routes options listed above—they replace the old ones.

Your takeaway:

1. Turn these APIs on once.
2. When you restrict a key (Web services/Android/iOS), tick only these APIs.
3. Web JS key stays “Don’t restrict” per our dev note.