Use X-goog-api-key header instead of URL parameter for API authentication

This change implements Google's recommended REST API authentication practice
by using the X-goog-api-key header instead of passing the API key as a URL
parameter. This improves security and follows modern API standards.

Changes:
- Added add_auth_header method to set X-goog-api-key header
- Updated get and post methods to use header authentication
- Modified generate_auth_url to exclude API key from URL parameters
- Updated all test specs to expect header-based authentication
- Client ID authentication continues to work unchanged

Fixes #3

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: langsharpe

lib/google_maps_service/client.rb

@@ -142,6 +142,7 @@ def get(path, params, base_url: DEFAULT_BASE_URL, accepts_client_id: true, custo
           request_query_ticket
           request = Net::HTTP::Get.new(url)
           request["User-Agent"] = user_agent
+          add_auth_header(request, accepts_client_id)
           response = Net::HTTP.start(url.hostname, url.port, use_ssl: url.scheme == "https") do |http|
             http.request(request)
           end
@@ -171,6 +172,7 @@ def post(path, params, base_url: DEFAULT_BASE_URL, accepts_client_id: true, cust
           request_query_ticket
           request = Net::HTTP::Post.new(url)
           request["User-Agent"] = user_agent
+          add_auth_header(request, accepts_client_id)
           request["X-Goog-FieldMask"] = field_mask if field_mask
           request["Content-Type"] = "application/json"
           request.body = MultiJson.dump(params)
@@ -204,6 +206,26 @@ def release_query_ticket
       @qps_queue << Time.now if @qps_queue
     end
 
+    # Add authentication headers to the request.
+    #
+    # @param [Net::HTTPRequest] request The HTTP request object.
+    # @param [Boolean] accepts_client_id Sign the request using API {#keys} instead of {#client_id}.
+    #
+    # @return [void]
+    def add_auth_header(request, accepts_client_id)
+      if accepts_client_id && @client_id && @client_secret
+        # Client ID authentication doesn't use headers
+        return
+      end
+
+      if @key
+        request["X-goog-api-key"] = @key
+        return
+      end
+
+      raise ArgumentError, "Must provide API key for this API. It does not accept enterprise credentials."
+    end
+
     # Returns the path and query string portion of the request URL,
     # first adding any necessary parameters.
     #
@@ -229,9 +251,9 @@ def generate_auth_url(path, params, accepts_client_id)
         return path + "&signature=" + sig
       end
 
+      # For API key authentication, we now use headers instead of URL parameters
       if @key
-        params << ["key", @key]
-        return path + "?" + GoogleMapsService::Url.urlencode_params(params)
+        return params.empty? ? path : path + "?" + GoogleMapsService::Url.urlencode_params(params)
       end
 
       raise ArgumentError, "Must provide API key for this API. It does not accept enterprise credentials."

spec/google_maps_service/apis/directions_spec.rb

@@ -5,15 +5,16 @@
 
   before(:example) do
     stub_request(:get, /https:\/\/maps.googleapis.com\/maps\/api\/directions\/.*/)
+      .with(headers: {"X-goog-api-key" => api_key})
       .to_return(status: 200, headers: {"Content-Type" => "application/json"}, body: '{"status":"OK","results":[]}')
   end
 
   context "simple directions" do
     it "should call Google Maps Web Service" do
       # Simplest directions request. Driving directions by default.
       client.directions("Sydney", "Melbourne")
-      expect(a_request(:get, "https://maps.googleapis.com/maps/api/directions/json?origin=Sydney&destination=Melbourne&key=%s" %
-                          api_key)).to have_been_made
+      expect(a_request(:get, "https://maps.googleapis.com/maps/api/directions/json?origin=Sydney&destination=Melbourne")
+        .with(headers: {"X-goog-api-key" => api_key})).to have_been_made
     end
   end
 
@@ -24,8 +25,8 @@
         avoid: ["highways", "tolls", "ferries"],
         units: "metric",
         region: "au")
-      expect(a_request(:get, "https://maps.googleapis.com/maps/api/directions/json?origin=Sydney&avoid=highways%%7Ctolls%%7Cferries&destination=Melbourne&mode=bicycling&key=%s&units=metric&region=au" %
-                          api_key)).to have_been_made
+      expect(a_request(:get, "https://maps.googleapis.com/maps/api/directions/json?origin=Sydney&avoid=highways%%7Ctolls%%7Cferries&destination=Melbourne&mode=bicycling&units=metric&region=au")
+        .with(headers: {"X-goog-api-key" => api_key})).to have_been_made
     end
   end
 
@@ -35,8 +36,8 @@
       client.directions("Sydney Town Hall", "Parramatta, NSW",
         mode: "transit",
         departure_time: now)
-      expect(a_request(:get, "https://maps.googleapis.com/maps/api/directions/json?origin=Sydney+Town+Hall&key=%s&destination=Parramatta%%2C+NSW&mode=transit&departure_time=%d" %
-                          [api_key, now.to_i])).to have_been_made
+      expect(a_request(:get, "https://maps.googleapis.com/maps/api/directions/json?origin=Sydney+Town+Hall&destination=Parramatta%%2C+NSW&mode=transit&departure_time=%d" % now.to_i)
+        .with(headers: {"X-goog-api-key" => api_key})).to have_been_made
     end
   end
 
@@ -46,8 +47,8 @@
       client.directions("Sydney Town Hall", "Parramatta, NSW",
         mode: "transit",
         arrival_time: an_hour_before_now)
-      expect(a_request(:get, "https://maps.googleapis.com/maps/api/directions/json?origin=Sydney+Town+Hall&arrival_time=%d&destination=Parramatta%%2C+NSW&mode=transit&key=%s" %
-                          [an_hour_before_now.to_i, api_key])).to have_been_made
+      expect(a_request(:get, "https://maps.googleapis.com/maps/api/directions/json?origin=Sydney+Town+Hall&arrival_time=%d&destination=Parramatta%%2C+NSW&mode=transit" % an_hour_before_now.to_i)
+        .with(headers: {"X-goog-api-key" => api_key})).to have_been_made
     end
   end
 
@@ -77,7 +78,8 @@
     it "should call Google Maps Web Service" do
       client.directions("Town Hall, Sydney", "Parramatta, NSW",
         mode: "bicycling")
-      expect(a_request(:get, "https://maps.googleapis.com/maps/api/directions/json?origin=Town+Hall%%2C+Sydney&destination=Parramatta%%2C+NSW&mode=bicycling&key=%s" % api_key)).to have_been_made
+      expect(a_request(:get, "https://maps.googleapis.com/maps/api/directions/json?origin=Town+Hall%%2C+Sydney&destination=Parramatta%%2C+NSW&mode=bicycling")
+        .with(headers: {"X-goog-api-key" => api_key})).to have_been_made
     end
   end
 
@@ -87,15 +89,17 @@
       client.directions("Brooklyn", "Queens",
         mode: "transit",
         departure_time: now)
-      expect(a_request(:get, "https://maps.googleapis.com/maps/api/directions/json?origin=Brooklyn&key=%s&destination=Queens&mode=transit&departure_time=%d" % [api_key, now.to_i])).to have_been_made
+      expect(a_request(:get, "https://maps.googleapis.com/maps/api/directions/json?origin=Brooklyn&destination=Queens&mode=transit&departure_time=%d" % now.to_i)
+        .with(headers: {"X-goog-api-key" => api_key})).to have_been_made
     end
   end
 
   context "boston to concord via charlestown and lexington" do
     it "should call Google Maps Web Service" do
       client.directions("Boston, MA", "Concord, MA",
         waypoints: ["Charlestown, MA", "Lexington, MA"])
-      expect(a_request(:get, "https://maps.googleapis.com/maps/api/directions/json?origin=Boston%%2C+MA&destination=Concord%%2C+MA&waypoints=Charlestown%%2C+MA%%7CLexington%%2C+MA&key=%s" % api_key)).to have_been_made
+      expect(a_request(:get, "https://maps.googleapis.com/maps/api/directions/json?origin=Boston%%2C+MA&destination=Concord%%2C+MA&waypoints=Charlestown%%2C+MA%%7CLexington%%2C+MA")
+        .with(headers: {"X-goog-api-key" => api_key})).to have_been_made
     end
   end
 
@@ -107,22 +111,24 @@
           "Connawarra, SA",
           "McLaren Vale, SA"],
         optimize_waypoints: true)
-      expect(a_request(:get, "https://maps.googleapis.com/maps/api/directions/json?origin=Adelaide%%2C+SA&destination=Adelaide%%2C+SA&waypoints=optimize%%3Atrue%%7CBarossa+Valley%%2C+SA%%7CClare%%2C+SA%%7CConnawarra%%2C+SA%%7CMcLaren+Vale%%2C+SA&key=%s" % api_key)).to have_been_made
+      expect(a_request(:get, "https://maps.googleapis.com/maps/api/directions/json?origin=Adelaide%%2C+SA&destination=Adelaide%%2C+SA&waypoints=optimize%%3Atrue%%7CBarossa+Valley%%2C+SA%%7CClare%%2C+SA%%7CConnawarra%%2C+SA%%7CMcLaren+Vale%%2C+SA")
+        .with(headers: {"X-goog-api-key" => api_key})).to have_been_made
     end
   end
 
   context "toledo to madrid in spain" do
     it "should call Google Maps Web Service" do
       client.directions("Toledo", "Madrid",
         region: "es")
-      expect(a_request(:get, "https://maps.googleapis.com/maps/api/directions/json?origin=Toledo&region=es&destination=Madrid&key=%s" %
-                          api_key)).to have_been_made
+      expect(a_request(:get, "https://maps.googleapis.com/maps/api/directions/json?origin=Toledo&region=es&destination=Madrid")
+        .with(headers: {"X-goog-api-key" => api_key})).to have_been_made
     end
   end
 
   context "zero results returns response" do
     before(:example) do
       stub_request(:get, /https:\/\/maps.googleapis.com\/maps\/api\/directions\/.*/)
+        .with(headers: {"X-goog-api-key" => api_key})
         .to_return(status: 200, headers: {"Content-Type" => "application/json"}, body: '{"status":"ZERO_RESULTS","routes":[]}')
     end
 
@@ -135,6 +141,7 @@
   context "can return full response" do
     before(:example) do
       stub_request(:get, /https:\/\/maps.googleapis.com\/maps\/api\/directions\/.*/)
+        .with(headers: {"X-goog-api-key" => api_key})
         .to_return(status: 200, headers: {"Content-Type" => "application/json"}, body: '{"status":"OK","routes":[]}')
     end
 
@@ -149,15 +156,17 @@
       client.directions("Toledo", "Madrid",
         region: "es",
         language: "es")
-      expect(a_request(:get, "https://maps.googleapis.com/maps/api/directions/json?origin=Toledo&region=es&destination=Madrid&key=%s&language=es" % api_key)).to have_been_made
+      expect(a_request(:get, "https://maps.googleapis.com/maps/api/directions/json?origin=Toledo&region=es&destination=Madrid&language=es")
+        .with(headers: {"X-goog-api-key" => api_key})).to have_been_made
     end
   end
 
   context "alternatives" do
     it "should call Google Maps Web Service" do
       client.directions("Sydney Town Hall", "Parramatta Town Hall",
         alternatives: true)
-      expect(a_request(:get, "https://maps.googleapis.com/maps/api/directions/json?origin=Sydney+Town+Hall&destination=Parramatta+Town+Hall&alternatives=true&key=%s" % api_key)).to have_been_made
+      expect(a_request(:get, "https://maps.googleapis.com/maps/api/directions/json?origin=Sydney+Town+Hall&destination=Parramatta+Town+Hall&alternatives=true")
+        .with(headers: {"X-goog-api-key" => api_key})).to have_been_made
     end
   end
 end

spec/google_maps_service/apis/distance_matrix_spec.rb

@@ -5,6 +5,7 @@
 
   before(:example) do
     stub_request(:get, /https:\/\/maps.googleapis.com\/maps\/api\/distancematrix\/.*/)
+      .with(headers: {"X-goog-api-key" => api_key})
       .to_return(status: 200, headers: {"Content-Type" => "application/json"}, body: '{"status":"OK","rows":[]}')
   end
 
@@ -21,7 +22,8 @@
         "The Pinnacles, Australia"]
 
       client.distance_matrix(origins, destinations)
-      expect(a_request(:get, "https://maps.googleapis.com/maps/api/distancematrix/json?key=%s&origins=Perth%%2C+Australia%%7CSydney%%2C+Australia%%7CMelbourne%%2C+Australia%%7CAdelaide%%2C+Australia%%7CBrisbane%%2C+Australia%%7CDarwin%%2C+Australia%%7CHobart%%2C+Australia%%7CCanberra%%2C+Australia&destinations=Uluru%%2C+Australia%%7CKakadu%%2C+Australia%%7CBlue+Mountains%%2C+Australia%%7CBungle+Bungles%%2C+Australia%%7CThe+Pinnacles%%2C+Australia" % api_key)).to have_been_made
+      expect(a_request(:get, "https://maps.googleapis.com/maps/api/distancematrix/json?origins=Perth%%2C+Australia%%7CSydney%%2C+Australia%%7CMelbourne%%2C+Australia%%7CAdelaide%%2C+Australia%%7CBrisbane%%2C+Australia%%7CDarwin%%2C+Australia%%7CHobart%%2C+Australia%%7CCanberra%%2C+Australia&destinations=Uluru%%2C+Australia%%7CKakadu%%2C+Australia%%7CBlue+Mountains%%2C+Australia%%7CBungle+Bungles%%2C+Australia%%7CThe+Pinnacles%%2C+Australia")
+        .with(headers: {"X-goog-api-key" => api_key})).to have_been_made
     end
   end
 
@@ -32,7 +34,8 @@
         {lat: 42.8863855, lng: -78.8781627}]
 
       client.distance_matrix(origins, destinations)
-      expect(a_request(:get, "https://maps.googleapis.com/maps/api/distancematrix/json?key=%s&origins=Bobcaygeon+ON%%7C41.432060%%2C-81.389920&destinations=43.012486%%2C-83.696415%%7C42.886386%%2C-78.878163" % api_key)).to have_been_made
+      expect(a_request(:get, "https://maps.googleapis.com/maps/api/distancematrix/json?origins=Bobcaygeon+ON%%7C41.432060%%2C-81.389920&destinations=43.012486%%2C-83.696415%%7C42.886386%%2C-78.878163")
+        .with(headers: {"X-goog-api-key" => api_key})).to have_been_made
     end
   end
 
@@ -53,7 +56,8 @@
         language: "en-AU",
         avoid: "tolls",
         units: "imperial")
-      expect(a_request(:get, "https://maps.googleapis.com/maps/api/distancematrix/json?origins=Perth%%2C+Australia%%7CSydney%%2C+Australia%%7CMelbourne%%2C+Australia%%7CAdelaide%%2C+Australia%%7CBrisbane%%2C+Australia%%7CDarwin%%2C+Australia%%7CHobart%%2C+Australia%%7CCanberra%%2C+Australia&language=en-AU&avoid=tolls&mode=driving&key=%s&units=imperial&destinations=Uluru%%2C+Australia%%7CKakadu%%2C+Australia%%7CBlue+Mountains%%2C+Australia%%7CBungle+Bungles%%2C+Australia%%7CThe+Pinnacles%%2C+Australia" % api_key)).to have_been_made
+      expect(a_request(:get, "https://maps.googleapis.com/maps/api/distancematrix/json?origins=Perth%%2C+Australia%%7CSydney%%2C+Australia%%7CMelbourne%%2C+Australia%%7CAdelaide%%2C+Australia%%7CBrisbane%%2C+Australia%%7CDarwin%%2C+Australia%%7CHobart%%2C+Australia%%7CCanberra%%2C+Australia&language=en-AU&avoid=tolls&mode=driving&units=imperial&destinations=Uluru%%2C+Australia%%7CKakadu%%2C+Australia%%7CBlue+Mountains%%2C+Australia%%7CBungle+Bungles%%2C+Australia%%7CThe+Pinnacles%%2C+Australia")
+        .with(headers: {"X-goog-api-key" => api_key})).to have_been_made
     end
   end
 
@@ -65,8 +69,8 @@
       client.distance_matrix(origins, destinations,
         language: "fr-FR",
         mode: "bicycling")
-      expect(a_request(:get, "https://maps.googleapis.com/maps/api/distancematrix/json?key=%s&language=fr-FR&mode=bicycling&origins=Vancouver+BC%%7CSeattle&destinations=San+Francisco%%7CVictoria+BC" %
-                          api_key)).to have_been_made
+      expect(a_request(:get, "https://maps.googleapis.com/maps/api/distancematrix/json?language=fr-FR&mode=bicycling&origins=Vancouver+BC%%7CSeattle&destinations=San+Francisco%%7CVictoria+BC")
+        .with(headers: {"X-goog-api-key" => api_key})).to have_been_made
     end
   end
 

spec/google_maps_service/apis/elevation_spec.rb

@@ -5,35 +5,40 @@
 
   before(:example) do
     stub_request(:get, /https:\/\/maps.googleapis.com\/maps\/api\/elevation\/.*/)
+      .with(headers: {"X-goog-api-key" => api_key})
       .to_return(status: 200, headers: {"Content-Type" => "application/json"}, body: '{"status":"OK","results":[]}')
   end
 
   context "elevation single" do
     it "should call Google Maps Web Service" do
       client.elevation([40.714728, -73.998672])
-      expect(a_request(:get, "https://maps.googleapis.com/maps/api/elevation/json?locations=40.714728%%2C-73.998672&key=%s" % api_key)).to have_been_made
+      expect(a_request(:get, "https://maps.googleapis.com/maps/api/elevation/json?locations=40.714728%%2C-73.998672")
+        .with(headers: {"X-goog-api-key" => api_key})).to have_been_made
     end
   end
 
   context "elevation single list" do
     it "should call Google Maps Web Service" do
       client.elevation([[40.714728, -73.998672]])
-      expect(a_request(:get, "https://maps.googleapis.com/maps/api/elevation/json?locations=40.714728%%2C-73.998672&key=%s" % api_key)).to have_been_made
+      expect(a_request(:get, "https://maps.googleapis.com/maps/api/elevation/json?locations=40.714728%%2C-73.998672")
+        .with(headers: {"X-goog-api-key" => api_key})).to have_been_made
     end
   end
 
   context "elevation multiple" do
     it "should call Google Maps Web Service" do
       locations = [[40.714728, -73.998672], [-34.397, 150.644]]
       client.elevation(locations)
-      expect(a_request(:get, "https://maps.googleapis.com/maps/api/elevation/json?locations=40.714728%%2C-73.998672%%7C-34.397000%%2C150.644000&key=%s" % api_key)).to have_been_made
+      expect(a_request(:get, "https://maps.googleapis.com/maps/api/elevation/json?locations=40.714728%%2C-73.998672%%7C-34.397000%%2C150.644000")
+        .with(headers: {"X-goog-api-key" => api_key})).to have_been_made
     end
   end
 
   context "elevation along path" do
     context "with single point" do
       before(:example) do
         stub_request(:get, /https:\/\/maps.googleapis.com\/maps\/api\/elevation\/.*/)
+          .with(headers: {"X-goog-api-key" => api_key})
           .to_return(status: 200, headers: {"Content-Type" => "application/json"}, body: '{"results": [], "status": "INVALID_REQUEST"}')
       end
 
@@ -47,7 +52,8 @@
         path = [[40.714728, -73.998672], [-34.397, 150.644]]
 
         client.elevation_along_path(path, 5)
-        expect(a_request(:get, "https://maps.googleapis.com/maps/api/elevation/json?path=40.714728%%2C-73.998672%%7C-34.397000%%2C150.644000&key=%s&samples=5" % api_key)).to have_been_made
+        expect(a_request(:get, "https://maps.googleapis.com/maps/api/elevation/json?path=40.714728%%2C-73.998672%%7C-34.397000%%2C150.644000&samples=5")
+          .with(headers: {"X-goog-api-key" => api_key})).to have_been_made
       end
     end
 
@@ -56,7 +62,8 @@
         path = "gfo}EtohhUxD@bAxJmGF"
 
         client.elevation_along_path(path, 5)
-        expect(a_request(:get, "https://maps.googleapis.com/maps/api/elevation/json?path=enc:gfo}EtohhUxD@bAxJmGF&key=%s&samples=5" % api_key)).to have_been_made
+        expect(a_request(:get, "https://maps.googleapis.com/maps/api/elevation/json?path=enc:gfo}EtohhUxD@bAxJmGF&samples=5")
+          .with(headers: {"X-goog-api-key" => api_key})).to have_been_made
       end
     end
   end