Google Maps API Setup Guide for Magento 2

Configure your Google Maps API key for the Shipping Costs Based on Distance extension. This guide walks you through creating a Google Cloud project, enabling the required APIs, and setting up your credentials.

Required API

The extension requires the Distance Matrix API from Google Cloud Platform. This API calculates travel distances between your store location and customer addresses.

Step 1: Create a Google Cloud Project

1. Go to Google Cloud Console
2. Sign in with your Google account
3. Click the project dropdown at the top of the page
4. Click New Project
5. Enter a project name (e.g., "Magento Shipping")
6. Click Create
7. Wait for the project to be created, then select it

Step 2: Enable Billing

The Distance Matrix API requires a billing account. Google provides $200 free credit per month.

1. Go to Billing in the left menu
2. Click Link a billing account
3. Follow the prompts to set up billing
4. Add a payment method

Note: You won't be charged unless you exceed the free tier limits.

Step 3: Enable Distance Matrix API

1. Go to APIs & Services → Library
2. Search for "Distance Matrix API"
3. Click on Distance Matrix API
4. Click Enable

Step 4: Create API Key

1. Go to APIs & Services → Credentials
2. Click + Create Credentials
3. Select API key
4. Your new API key will be displayed
5. Click Copy to copy the key
6. Click Close

Step 5: Restrict Your API Key (Recommended)

Protect your API key from unauthorized use:

1. In the Credentials page, click on your API key name
2. Under Application restrictions:
   • For testing: Select None
   • For production: Select IP addresses and add your server IP
3. Under API restrictions:
   • Select Restrict key
   • Check Distance Matrix API
4. Click Save

Step 6: Configure in Magento

1. Go to Magmodules → Shipping Costs Based on Distance
2. Under General → API and Location Details:
   • Paste your API key in the API Key field
   • Enter your Store Address (full address including country)
3. Click Test Credentials to verify the connection
4. Click Save Config

API Pricing

Google charges per request to the Distance Matrix API:

Monthly free credit: $200 (covers ~40,000 requests)

When are requests made?

• When a customer enters/changes their shipping address at checkout
• When using the product page shipping estimator
• During selftest/credential testing

Monitoring Usage

Track your API usage to manage costs:

1. Go to APIs & Services → Dashboard
2. Click on Distance Matrix API
3. View the Traffic chart for request counts
4. Check Errors for any failed requests

Set Up Billing Alerts

Store Address Best Practices

The store address you enter is the origin point for all distance calculations.

Do:

• Use your warehouse or fulfillment center address
• Include full address: street, city, postal code, country
• Use the address format Google Maps recognizes

Examples of Good Addresses:

123 Warehouse Street, Amsterdam, 1012 AB, Netherlands
456 Distribution Center Dr, Rotterdam, 3011 BC, NL

Don't:

• Use PO Box addresses
• Use incomplete addresses
• Use addresses Google can't find

Testing Your Setup

After configuration, verify everything works:

1. Test Credentials Button

   • Click the button in configuration
   • Should show success message

2. Selftest Command

   • Run: bin/magento distancebasedshipping:selftest
   • Checks API connectivity and configuration

3. Checkout Test

   • Add a product to cart
   • Go to checkout
   • Enter a shipping address
   • Verify distance-based shipping option appears

Troubleshooting API Issues

"API key not valid"

"This API project is not authorized"

"You have exceeded your daily request quota"

"REQUEST_DENIED"

"ZERO_RESULTS"

Need More Help?

Documentation:

• All Help Articles - Complete documentation overview

Support:

• Contact Support - Get help from our team

Google Resources:

• Distance Matrix API Documentation
• Google Cloud Console