Setup Google Maps API for Distance Shipping

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

This extension supports two Google Maps APIs:

1. Routes API (Recommended) - The new API with improved performance and features
2. Distance Matrix API (Legacy) - The older API for backward compatibility

You can select which API to use in the configuration panel. Both APIs calculate travel distances between your store location and customer addresses.

For New Installations: We recommend using the Routes API.

For Existing Installations: Your installation will continue using Distance Matrix API by default. You can migrate to Routes API at your convenience by enabling it in Google Cloud Console and switching the configuration.

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

Both Google Maps APIs require 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 the API

Choose which API to enable based on your preference:

Option A: Routes API (Recommended for new installations)

Option B: Distance Matrix API (Legacy - for existing installations)

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 the API you're using:
     • Routes API (if using the new API)
     • Distance Matrix API (if using the legacy API)
     • You can check both if you want to test migration
4. Click Save

Step 6: Configure in Magento

1. Go to Magmodules → Shipping Costs Based on Distance
2. Under General → API and Location Details:
   • Google Maps API Version: Select which API to use
     • Routes API (Recommended) - Use the new Routes API
     • Distance Matrix API (Legacy) - Use the legacy API (default for existing installations)
   • 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

Important: Make sure the API version you select matches the API you enabled in Google Cloud Console.

API Pricing

Google charges per request. Pricing varies by API:

• Routes API (Compute Route Matrix): See current pricing at Google Maps Platform Pricing
• Distance Matrix API (Legacy): See current pricing at Google Maps Platform Pricing

Monthly free credit: $200

Pricing may vary by region and usage tier. The Routes API generally offers better performance and may have different pricing tiers than the legacy Distance Matrix API.

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 the API you're using:
   • Routes API (if using the new API)
   • Distance Matrix API (if using the legacy 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:

• Routes API Documentation
• Google Cloud Console