Billing & Permissions
Required API Permissions
Your Google Cloud project needs these APIs enabled:
| API | Required? | When it's used |
|---|---|---|
| Maps JavaScript API | Yes | Interactive map rendering |
| Static Maps API | Recommended | Placeholder image before JS loads (unless you provide a #placeholder slot) |
| Geocoding API | Optional | Server-side geocode proxy for query strings (e.g. center="Brooklyn Bridge, NY") |
| Places API | Optional | Client-side fallback when geocode proxy is unavailable and using query strings |
Cost Breakdown
Google Maps uses a pay-per-use model. Here's what each interaction costs:
| Action | API Charged | Cost per 1,000 | When it happens |
|---|---|---|---|
| Page loads with map placeholder | Static Maps API | $2 | Every page view (unless #placeholder slot overrides) |
| User interacts with map (hover/click) | Maps JavaScript API | $7 | Only when user triggers the map to load |
| Location query resolved server-side | Geocoding API | $5 | Only when using string queries like "Sydney, Australia" |
| Location query resolved client-side | Places API | $17 | Fallback when geocode proxy is not enabled |
How Nuxt Scripts Minimizes Costs
Nuxt Scripts is designed to reduce Google Maps billing:
Lazy loading: The JavaScript API ($7/1000) only loads when a user interacts with the map. If they never hover or click, you only pay for the static placeholder ($2/1000).
Geocode proxy: When you enable googleMaps: true in the registry, the server resolves location queries via the Geocoding API ($5/1000) instead of the client-side Places API ($17/1000). That's a 70% cost reduction for query resolution.
Static maps proxy: Placeholder images are routed through your server, which enables caching. Repeated visits to the same page serve cached images instead of hitting Google's API again.
Cost Optimization Tips
- Use coordinates, not queries: Pass
centeras{ lat, lng }instead of"Sydney, Australia"to avoid geocoding charges entirely. - Provide a
#placeholderslot: Replace the static map image with your own placeholder to eliminate Static Maps API charges.<ScriptGoogleMaps> <template #placeholder> <img src="/my-map-placeholder.webp" alt="Map"> </template> </ScriptGoogleMaps> - Use
trigger="immediate"only when needed: The default trigger (mouseover/mousedown) means most page views won't load the JS API. Settingtrigger="immediate"charges $7/1000 on every page view. - Consider Iframe Embed for non-interactive maps: If you don't need full interactivity, the Google Maps Embed API is free and you can load it with
useScript().
Monthly Cost Estimates
Assuming 100,000 page views per month:
| Scenario | Monthly Cost |
|---|---|
| Static placeholder only (no interaction) | ~$200 |
| 20% of visitors interact with map | ~$340 |
| All visitors interact with map | ~$900 |
Custom #placeholder slot, 20% interact | ~$140 |
These estimates assume you have Google's $200/month free credit. Most small to mid-size sites fall within the free tier.
Map Styling
Google Maps supports two styling approaches: legacy JSON styles and cloud-based map IDs. Both work with Nuxt Scripts, including the static map placeholder.
<ScriptGoogleMaps>
The <ScriptGoogleMaps> component is a wrapper around the useScriptGoogleMaps() composable. It provides a simple way to embed Google Maps in your Nuxt app.