0
# Geocoding Providers
1

2
Node Geocoder supports 23 geocoding service providers, each with specific configuration options and capabilities.
3

4
## Capabilities
5

6
### Supported Providers
7

8
Complete list of supported geocoding providers with their identifier names.
9

10
```javascript { .api }
11
/**
12
 * Supported provider names for use with NodeGeocoder factory
13
 */
14
type ProviderName = 
15
  | 'google'              // Google Maps Geocoding API (default)
16
  | 'here'                // HERE Geocoding API
17
  | 'agol'                // ArcGIS Online Geocoding Service
18
  | 'freegeoip'           // FreeGeoIP service
19
  | 'datasciencetoolkit'  // Data Science Toolkit
20
  | 'openstreetmap'       // OpenStreetMap Nominatim
21
  | 'pickpoint'           // PickPoint API
22
  | 'locationiq'          // LocationIQ API
23
  | 'mapquest'            // MapQuest API
24
  | 'mapzen'              // Mapzen Search API
25
  | 'openmapquest'        // Open MapQuest API
26
  | 'yandex'              // Yandex Maps API
27
  | 'geocodio'            // Geocodio API
28
  | 'opencage'            // OpenCage Data API
29
  | 'nominatimmapquest'   // Nominatim MapQuest
30
  | 'tomtom'              // TomTom API
31
  | 'virtualearth'        // Microsoft Bing Maps
32
  | 'smartystreets'       // SmartyStreets API
33
  | 'teleport'            // Teleport API
34
  | 'opendatafrance'      // OpenData France
35
  | 'mapbox'              // Mapbox Geocoding API
36
  | 'aplace'              // A-Place API
37
```
38

39
### Google Maps Provider
40

41
Google Maps Geocoding API with comprehensive location data and high accuracy.
42

43
```javascript { .api }
44
/**
45
 * Google Maps provider configuration
46
 */
47
interface GoogleOptions {
48
  /** Google API key */
49
  apiKey?: string;
50
  /** Google client ID for business accounts */
51
  clientId?: string;
52
  /** Language code for results (e.g., 'en', 'fr', 'de') */
53
  language?: string;
54
  /** Region biasing (e.g., 'us', 'uk', 'fr') */
55
  region?: string;
56
  /** Exclude partial matches from results */
57
  excludePartialMatches?: boolean;
58
  /** Channel for premium plan tracking */
59
  channel?: string;
60
}
61
```
62

63
**Usage Examples:**
64

65
```javascript
66
// Basic Google configuration
67
const geocoder = NodeGeocoder('google', {
68
  apiKey: 'YOUR_GOOGLE_API_KEY'
69
});
70

71
// Advanced Google configuration
72
const geocoder = NodeGeocoder('google', {
73
  apiKey: 'YOUR_API_KEY',
74
  language: 'fr',
75
  region: 'fr',
76
  excludePartialMatches: true
77
});
78

79
// Business account with client ID
80
const geocoder = NodeGeocoder('google', {
81
  clientId: 'your-client-id',
82
  apiKey: 'your-private-key',
83
  channel: 'your-channel'
84
});
85
```
86

87
### HERE Provider
88

89
HERE Geocoding API with flexible configuration options.
90

91
```javascript { .api }
92
/**
93
 * HERE provider configuration
94
 */
95
interface HereOptions {
96
  /** HERE API key (current authentication method) */
97
  apiKey?: string;
98
  /** HERE app ID (legacy authentication) */
99
  appId?: string;
100
  /** HERE app code (legacy authentication) */
101
  appCode?: string;
102
  /** Language preference */
103
  language?: string;
104
  /** Political view setting */
105
  politicalView?: string;
106
  /** Country preference */
107
  country?: string;
108
  /** State preference */
109
  state?: string;
110
  /** Use production environment */
111
  production?: boolean;
112
  /** Maximum number of results */
113
  limit?: number;
114
}
115
```
116

117
**Usage Examples:**
118

119
```javascript
120
// HERE with API key (recommended)
121
const geocoder = NodeGeocoder('here', {
122
  apiKey: 'YOUR_HERE_API_KEY',
123
  language: 'en-US'
124
});
125

126
// HERE with legacy app credentials
127
const geocoder = NodeGeocoder('here', {
128
  appId: 'YOUR_APP_ID',
129
  appCode: 'YOUR_APP_CODE',
130
  production: true
131
});
132
```
133

134
### OpenStreetMap Provider
135

136
OpenStreetMap Nominatim service with open data and no API key required.
137

138
```javascript { .api }
139
/**
140
 * OpenStreetMap provider configuration
141
 */
142
interface OpenStreetMapOptions {
143
  /** Language preference */
144
  language?: string;
145
  /** Custom Nominatim server URL */
146
  osmServer?: string;
147
}
148
```
149

150
**Usage Examples:**
151

152
```javascript
153
// Basic OpenStreetMap (no API key needed)
154
const geocoder = NodeGeocoder('openstreetmap');
155

156
// Custom language and server
157
const geocoder = NodeGeocoder('openstreetmap', {
158
  language: 'en',
159
  osmServer: 'https://your-nominatim-server.com'
160
});
161
```
162

163
### MapBox Provider
164

165
Mapbox Geocoding API with global coverage and customization options.
166

167
```javascript { .api }
168
/**
169
 * Mapbox provider configuration
170
 */
171
interface MapboxOptions {
172
  /** Mapbox access token */
173
  apiKey: string;
174
  /** Additional mapbox-specific options */
175
  [key: string]: any;
176
}
177
```
178

179
**Usage Examples:**
180

181
```javascript
182
const geocoder = NodeGeocoder('mapbox', {
183
  apiKey: 'YOUR_MAPBOX_ACCESS_TOKEN'
184
});
185
```
186

187
### TomTom Provider
188

189
TomTom Maps API with automotive-focused geocoding.
190

191
```javascript { .api }
192
/**
193
 * TomTom provider configuration
194
 */
195
interface TomTomOptions {
196
  /** TomTom API key */
197
  apiKey: string;
198
  /** Country preference */
199
  country?: string;
200
  /** Maximum number of results */
201
  limit?: number;
202
}
203
```
204

205
**Usage Examples:**
206

207
```javascript
208
const geocoder = NodeGeocoder('tomtom', {
209
  apiKey: 'YOUR_TOMTOM_API_KEY',
210
  country: 'US',
211
  limit: 5
212
});
213
```
214

215
### Yandex Provider
216

217
Yandex Maps API with comprehensive options for Russian and international locations.
218

219
```javascript { .api }
220
/**
221
 * Yandex provider configuration
222
 */
223
interface YandexOptions {
224
  /** Yandex API key */
225
  apiKey?: string;
226
  /** Language preference */
227
  language?: string;
228
  /** Maximum number of results */
229
  results?: number;
230
  /** Number of results to skip */
231
  skip?: number;
232
  /** Kind of toponym to search */
233
  kind?: string;
234
  /** Bounding box for search area */
235
  bbox?: string;
236
  /** Restrict search to bbox */
237
  rspn?: boolean;
238
}
239
```
240

241
**Usage Examples:**
242

243
```javascript
244
const geocoder = NodeGeocoder('yandex', {
245
  apiKey: 'YOUR_YANDEX_API_KEY',
246
  language: 'ru_RU',
247
  results: 10
248
});
249
```
250

251
### Free and Open Providers
252

253
Several providers that don't require API keys or have free tiers.
254

255
```javascript { .api }
256
/**
257
 * Free provider configurations
258
 */
259
interface FreeProviders {
260
  /** OpenStreetMap Nominatim - completely free */
261
  openstreetmap: {};
262
  /** FreeGeoIP - IP geocoding only */
263
  freegeoip: {};
264
  /** OpenData France - French addresses */
265
  opendatafrance: {};
266
  /** Data Science Toolkit - custom host option */
267
  datasciencetoolkit: { host?: string };
268
}
269
```
270

271
**Usage Examples:**
272

273
```javascript
274
// Free providers requiring no configuration
275
const osmGeocoder = NodeGeocoder('openstreetmap');
276
const ipGeocoder = NodeGeocoder('freegeoip');
277
const franceGeocoder = NodeGeocoder('opendatafrance');
278

279
// Data Science Toolkit with custom host
280
const dstkGeocoder = NodeGeocoder('datasciencetoolkit', {
281
  host: 'localhost:8080'
282
});
283
```
284

285
### API Key Required Providers
286

287
Providers that require API keys or authentication tokens.
288

289
```javascript { .api }
290
/**
291
 * API key required provider configurations
292
 */
293
interface ApiKeyProviders {
294
  google: GoogleOptions;
295
  here: HereOptions;
296
  mapquest: { apiKey: string };
297
  geocodio: { apiKey: string };
298
  opencage: { apiKey: string; [key: string]: any };
299
  locationiq: { apiKey: string };
300
  pickpoint: { apiKey: string; language?: string };
301
  virtualearth: { apiKey: string };
302
  tomtom: TomTomOptions;
303
  mapbox: MapboxOptions;
304
  yandex: YandexOptions;
305
  smartystreets: { auth_id: string; auth_token: string };
306
  teleport: { apiKey?: string; [key: string]: any };
307
  nominatimmapquest: { apiKey: string; language?: string };
308
  agol: { client_id: string; client_secret: string };
309
  aplace: { [key: string]: any };
310
}
311
```
312

313
### Provider Capabilities Matrix
314

315
Different providers support different features and geographic regions.
316

317
```javascript { .api }
318
/**
319
 * Provider capability information
320
 */
321
interface ProviderCapabilities {
322
  /** Supports forward geocoding (address to coordinates) */
323
  geocoding: boolean;
324
  /** Supports reverse geocoding (coordinates to address) */
325
  reverseGeocoding: boolean;
326
  /** Supports batch operations */
327
  batchGeocoding: boolean;
328
  /** Supports IPv4 address geocoding */
329
  ipv4Support: boolean;
330
  /** Supports IPv6 address geocoding */
331
  ipv6Support: boolean;
332
  /** Provides confidence scores */
333
  confidenceScores: boolean;
334
  /** Geographic coverage areas */
335
  coverage: string[];
336
}
337
```
338

339
**Provider Coverage Examples:**
340

341
```javascript
342
// Global coverage providers
343
const globalProviders = ['google', 'here', 'mapbox', 'opencage'];
344

345
// Regional specialists
346
const usProviders = ['smartystreets', 'geocodio'];  // US-focused
347
const franceProvider = ['opendatafrance'];           // France-focused
348

349
// IP geocoding specialists
350
const ipProviders = ['freegeoip'];
351

352
// Choose provider based on needs
353
const geocoder = globalProviders.includes(preferredProvider) 
354
  ? NodeGeocoder(preferredProvider, { apiKey: 'key' })
355
  : NodeGeocoder('openstreetmap');  // fallback to free option
356
```