0
# Client Configuration
1
2
Configure the Google Maps client for authentication, rate limiting, timeout handling, and request customization to optimize performance and reliability for your application.
3
4
## Capabilities
5
6
### Client Initialization
7
8
Create and configure a Google Maps API client with authentication credentials and operational parameters.
9
10
```python { .api }
11
class Client:
12
def __init__(self, key=None, client_id=None, client_secret=None,
13
timeout=None, connect_timeout=None, read_timeout=None,
14
retry_timeout=60, requests_kwargs=None,
15
queries_per_second=60, queries_per_minute=6000, channel=None,
16
retry_over_query_limit=True, experience_id=None,
17
requests_session=None,
18
base_url="https://maps.googleapis.com"):
19
"""
20
Initialize Google Maps API client.
21
22
Args:
23
key (str): Maps API key. Required unless using enterprise credentials.
24
Most users should use an API key.
25
client_id (str): Enterprise client ID for Maps API for Work customers.
26
Most users should use an API key instead.
27
client_secret (str): Enterprise client secret (base64 encoded).
28
Most users should use an API key instead.
29
timeout (int): Combined connect and read timeout for HTTP requests,
30
in seconds. Specify None for no timeout.
31
connect_timeout (int): Connection timeout for HTTP requests, in
32
seconds. Requires requests >= 2.4.0.
33
read_timeout (int): Read timeout for HTTP requests, in seconds.
34
Requires requests >= 2.4.0.
35
retry_timeout (int): Timeout across multiple retriable requests,
36
in seconds. Default: 60.
37
queries_per_second (int): Number of queries per second permitted.
38
Default: 60. Rate limiting will sleep when exceeded.
39
queries_per_minute (int): Number of queries per minute permitted.
40
Default: 6000. Rate limiting will sleep when exceeded.
41
channel (str): Channel parameter for Maps API for Work customers.
42
Used for tracking purposes. ASCII alphanumeric only.
43
retry_over_query_limit (bool): Whether to retry requests that exceed
44
query rate limits. Default: True.
45
experience_id (str): Value for X-Goog-Maps-Experience-ID header.
46
requests_kwargs (dict): Extra keyword arguments for requests library,
47
including proxy authentication settings.
48
requests_session (requests.Session): Reused persistent session.
49
base_url (str): Base URL for all requests. Default: Google Maps API server.
50
Should not have trailing slash.
51
52
Raises:
53
ValueError: When credentials are missing, incomplete, or invalid.
54
NotImplementedError: If connect_timeout and read_timeout are used
55
with requests < 2.4.0.
56
"""
57
```
58
59
### Experience ID Management
60
61
Set, get, and clear the X-Goog-Maps-Experience-ID header for request tracking and debugging.
62
63
```python { .api }
64
def set_experience_id(self, *experience_id_args):
65
"""
66
Set the experience ID header value.
67
68
Args:
69
*experience_id_args: Variable arguments to construct experience ID
70
"""
71
72
def get_experience_id(self):
73
"""
74
Get the current experience ID header value.
75
76
Returns:
77
str: Current experience ID value or None
78
"""
79
80
def clear_experience_id(self):
81
"""Clear the experience ID header value."""
82
```
83
84
## Usage Examples
85
86
### Basic API Key Authentication
87
88
```python
89
import googlemaps
90
91
# Initialize with API key (most common)
92
gmaps = googlemaps.Client(key='YOUR_API_KEY')
93
```
94
95
### Enterprise Authentication
96
97
```python
98
import googlemaps
99
100
# Initialize with enterprise credentials
101
gmaps = googlemaps.Client(
102
client_id='your_client_id',
103
client_secret='your_base64_encoded_secret',
104
channel='your_channel'
105
)
106
```
107
108
### Rate Limiting Configuration
109
110
```python
111
import googlemaps
112
113
# Configure custom rate limits
114
gmaps = googlemaps.Client(
115
key='YOUR_API_KEY',
116
queries_per_second=10, # Limit to 10 QPS
117
queries_per_minute=500, # Limit to 500 QPM
118
retry_over_query_limit=True # Retry when limits exceeded
119
)
120
```
121
122
### Timeout and Retry Configuration
123
124
```python
125
import googlemaps
126
127
# Configure timeouts and retries
128
gmaps = googlemaps.Client(
129
key='YOUR_API_KEY',
130
timeout=30, # 30 second total timeout
131
retry_timeout=120, # 2 minute retry timeout
132
retry_over_query_limit=False # Don't retry rate limit errors
133
)
134
```
135
136
### Advanced Request Configuration
137
138
```python
139
import googlemaps
140
import requests
141
142
# Custom session with proxy settings
143
session = requests.Session()
144
session.proxies = {'https': 'http://proxy.example.com:8080'}
145
146
gmaps = googlemaps.Client(
147
key='YOUR_API_KEY',
148
requests_session=session,
149
requests_kwargs={
150
'headers': {'Custom-Header': 'value'},
151
'auth': ('username', 'password')
152
}
153
)
154
```
155
156
### Experience ID Tracking
157
158
```python
159
import googlemaps
160
161
gmaps = googlemaps.Client(key='YOUR_API_KEY')
162
163
# Set experience ID for request tracking
164
gmaps.set_experience_id('my-app-v1.0', 'user-session-123')
165
166
# Make API calls (all will include the experience ID header)
167
result = gmaps.geocode('1600 Amphitheatre Parkway')
168
169
# Check current experience ID
170
current_id = gmaps.get_experience_id()
171
172
# Clear experience ID
173
gmaps.clear_experience_id()
174
```