Add optional user location information to GrokSearchTool

This allows customizing the scope of the web search.

Author: kzu

src/xAI.Tests/ChatClientTests.cs

@@ -173,6 +173,32 @@ public async Task GrokInvokesHostedSearchTool()
         Assert.Contains(urls, x => x.PathAndQuery.Contains("/TSLA"));
     }
 
+    [SecretsFact("XAI_API_KEY")]
+    public async Task GrokInvokesHostedSearchWithCity()
+    {
+        var messages = new Chat()
+        {
+            { "system", "You are an assistant that uses web search to respond" },
+            { "user", "Que se puede hacer en el verano por la zona? Lo mas popular?" },
+        };
+
+        var grok = new GrokClient(Configuration["XAI_API_KEY"]!).AsIChatClient("grok-4-fast");
+
+        var options = new GrokChatOptions
+        {
+            Include = [IncludeOption.WebSearchCallOutput],
+            Tools = [new GrokSearchTool {
+                Country = "AR",
+                City = "Concepcion del Uruguay"
+            }]
+        };
+
+        var response = await grok.GetResponseAsync(messages, options);
+        var text = response.Text;
+
+        Assert.Contains("termas", text, StringComparison.OrdinalIgnoreCase);
+    }
+
     [SecretsFact("XAI_API_KEY")]
     public async Task GrokInvokesGrokSearchToolIncludesDomain()
     {

src/xAI.Tests/GrokConversionTests.cs

@@ -74,6 +74,57 @@ public void AsTool_WithWebSearch_ImageUnderstanding()
         Assert.True(tool.WebSearch.EnableImageUnderstanding);
     }
 
+    [Fact]
+    public void AsTool_WithWebSearch_UserLocation()
+    {
+        var webSearch = new GrokSearchTool
+        {
+            Country = "US",
+            Region = "California",
+            City = "San Francisco",
+            Timezone = "America/Los_Angeles"
+        };
+
+        var tool = webSearch.AsProtocolTool();
+
+        Assert.NotNull(tool?.WebSearch);
+        Assert.NotNull(tool.WebSearch.UserLocation);
+        Assert.Equal("US", tool.WebSearch.UserLocation.Country);
+        Assert.Equal("California", tool.WebSearch.UserLocation.Region);
+        Assert.Equal("San Francisco", tool.WebSearch.UserLocation.City);
+        Assert.Equal("America/Los_Angeles", tool.WebSearch.UserLocation.Timezone);
+    }
+
+    [Fact]
+    public void AsTool_WithWebSearch_UserLocation_PartialFields()
+    {
+        var webSearch = new GrokSearchTool
+        {
+            Country = "DE",
+            City = "Berlin"
+        };
+
+        var tool = webSearch.AsProtocolTool();
+
+        Assert.NotNull(tool?.WebSearch);
+        Assert.NotNull(tool.WebSearch.UserLocation);
+        Assert.Equal("DE", tool.WebSearch.UserLocation.Country);
+        Assert.Equal("Berlin", tool.WebSearch.UserLocation.City);
+        Assert.Empty(tool.WebSearch.UserLocation.Region);
+        Assert.Empty(tool.WebSearch.UserLocation.Timezone);
+    }
+
+    [Fact]
+    public void AsTool_WithWebSearch_NoUserLocation()
+    {
+        var webSearch = new GrokSearchTool();
+
+        var tool = webSearch.AsProtocolTool();
+
+        Assert.NotNull(tool?.WebSearch);
+        Assert.Null(tool.WebSearch.UserLocation);
+    }
+
     [Fact]
     public void AsTool_WithXSearch_ThrowsIfAllowedAndExcluded()
     {

src/xAI/GrokProtocolExtensions.cs

@@ -75,6 +75,22 @@ public static partial class GrokProtocolExtensions
                         EnableImageUnderstanding = grokSearch.EnableImageUnderstanding,
                     };
 
+                    if (grokSearch.Country is not null ||
+                        grokSearch.Region is not null ||
+                        grokSearch.City is not null ||
+                        grokSearch.Timezone is not null)
+                    {
+                        websearch.UserLocation = new WebSearchUserLocation();
+                        if (grokSearch.Country is not null)
+                            websearch.UserLocation.Country = grokSearch.Country;
+                        if (grokSearch.Region is not null)
+                            websearch.UserLocation.Region = grokSearch.Region;
+                        if (grokSearch.City is not null)
+                            websearch.UserLocation.City = grokSearch.City;
+                        if (grokSearch.Timezone is not null)
+                            websearch.UserLocation.Timezone = grokSearch.Timezone;
+                    }
+
                     if (grokSearch.AllowedDomains is { Count: > 0 } &&
                         grokSearch.ExcludedDomains is { Count: > 0 })
                         throw new NotSupportedException($"Cannot use {nameof(GrokSearchTool.AllowedDomains)} and {nameof(GrokSearchTool.ExcludedDomains)} together in the same request.");

src/xAI/GrokSearchTool.cs

@@ -20,4 +20,16 @@ public class GrokSearchTool : HostedWebSearchTool
 
     /// <summary>See https://docs.x.ai/docs/guides/tools/search-tools#enable-image-understanding</summary>
     public bool EnableImageUnderstanding { get; set; }
+
+    /// <summary>Sets the user's country for web search results, using the ISO alpha-2 code.</summary>
+    public string? Country { get; set; }
+
+    /// <summary>Additional free text information about the region to be used in the search.</summary>
+    public string? Region { get; set; }
+
+    /// <summary>Additional free text information about the city to be used in the search.</summary>
+    public string? City { get; set; }
+
+    /// <summary>IANA timezone name to be used in the search.</summary>
+    public string? Timezone { get; set; }
 }