0
# Geocoding Operations
1

2
Core geocoding functionality for converting addresses to coordinates and coordinates to addresses.
3

4
## Capabilities
5

6
### Geocode Method
7

8
Converts addresses, place names, or IP addresses to geographic coordinates.
9

10
```javascript { .api }
11
/**
12
 * Geocode an address, place name, or IP address to coordinates
13
 * @param {string|object} value - Address string, IP address, or query object
14
 * @param {function} callback - Optional callback function
15
 * @returns {Promise<GeocodeResult[]>} Promise resolving to array of geocoding results
16
 */
17
geocode(value, callback);
18
```
19

20
**Usage Examples:**
21

22
```javascript
23
const NodeGeocoder = require('node-geocoder');
24
const geocoder = NodeGeocoder('google', { apiKey: 'YOUR_API_KEY' });
25

26
// Simple address geocoding
27
const results = await geocoder.geocode('1600 Amphitheatre Parkway, Mountain View, CA');
28
console.log(results[0].latitude, results[0].longitude);
29

30
// IP address geocoding (provider dependent)
31
const ipResults = await geocoder.geocode('8.8.8.8');
32

33
// Structured address query
34
const structuredResults = await geocoder.geocode({
35
  address: '1600 Amphitheatre Parkway',
36
  country: 'US',
37
  zipcode: '94043'
38
});
39

40
// With callback style
41
geocoder.geocode('Paris, France', (err, results) => {
42
  if (err) {
43
    console.error(err);
44
    return;
45
  }
46
  console.log(results);
47
});
48
```
49

50
### Reverse Geocode Method
51

52
Converts geographic coordinates to addresses and place information.
53

54
```javascript { .api }
55
/**
56
 * Reverse geocode coordinates to address information
57
 * @param {object} query - Coordinates object with lat/lon properties
58
 * @param {function} callback - Optional callback function
59
 * @returns {Promise<GeocodeResult[]>} Promise resolving to array of reverse geocoding results
60
 */
61
reverse(query, callback);
62
```
63

64
**Usage Examples:**
65

66
```javascript
67
// Basic reverse geocoding
68
const results = await geocoder.reverse({ lat: 45.767, lon: 4.833 });
69
console.log(results[0].formattedAddress);
70

71
// With language preference
72
const frenchResults = await geocoder.reverse({
73
  lat: 45.767,
74
  lon: 4.833,
75
  language: 'fr'
76
});
77

78
// Provider-specific options (Google example)
79
const detailedResults = await geocoder.reverse({
80
  lat: 45.767,
81
  lon: 4.833,
82
  result_type: 'street_address',
83
  location_type: 'ROOFTOP'
84
});
85

86
// With callback style
87
geocoder.reverse({ lat: 45.767, lon: 4.833 }, (err, results) => {
88
  if (err) {
89
    console.error(err);
90
    return;
91
  }
92
  console.log(results[0].city);
93
});
94
```
95

96
### Batch Geocode Method
97

98
Processes multiple addresses in a single operation, with individual error handling. **Note:** All providers support batch operations, but only some (aplace, here, tomtom) have native batch implementations for better performance. Others fallback to individual geocode calls.
99

100
```javascript { .api }
101
/**
102
 * Batch geocode multiple addresses (native batch support: aplace, here, tomtom; others fallback to individual calls)
103
 * @param {string[]|object[]} values - Array of address strings or query objects
104
 * @param {function} callback - Optional callback function
105
 * @returns {Promise<BatchResult[]>} Promise resolving to array of batch results
106
 */
107
batchGeocode(values, callback);
108
```
109

110
**Usage Examples:**
111

112
```javascript
113
// Works with all providers (aplace, here, tomtom have native batch; others use individual calls)
114
const geocoder = NodeGeocoder('here', { apiKey: 'YOUR_API_KEY' });
115

116
// Batch geocoding with strings
117
const addresses = [
118
  '1600 Amphitheatre Parkway, Mountain View, CA',
119
  'Eiffel Tower, Paris, France',
120
  'Times Square, New York, NY'
121
];
122

123
const batchResults = await geocoder.batchGeocode(addresses);
124

125
// Process results with error handling
126
batchResults.forEach((result, index) => {
127
  if (result.error) {
128
    console.error(`Failed to geocode ${addresses[index]}:`, result.error);
129
  } else {
130
    console.log(`${addresses[index]}:`, result.value[0]);
131
  }
132
});
133

134
// Batch geocoding with query objects
135
const queries = [
136
  { address: '1600 Amphitheatre Parkway', country: 'US' },
137
  { address: 'Eiffel Tower', country: 'FR' },
138
  { address: 'Times Square', country: 'US' }
139
];
140

141
const queryResults = await geocoder.batchGeocode(queries);
142
```
143

144
### Confidence Filtering
145

146
Filter geocoding results based on confidence scores when supported by the provider.
147

148
```javascript { .api }
149
/**
150
 * Query object with confidence filtering
151
 */
152
interface ConfidenceQuery {
153
  /** Address to geocode */
154
  address: string;
155
  /** Minimum confidence threshold (0-1) */
156
  minConfidence: number;
157
  /** Other query parameters */
158
  [key: string]: any;
159
}
160
```
161

162
**Usage Examples:**
163

164
```javascript
165
// Filter results by confidence level
166
const highConfidenceResults = await geocoder.geocode({
167
  address: 'ambiguous street name',
168
  minConfidence: 0.8  // Only return results with 80%+ confidence
169
});
170

171
// Confidence is provider-dependent
172
const geocoder = NodeGeocoder('google', { apiKey: 'YOUR_API_KEY' });
173
const results = await geocoder.geocode('123 Main Street');
174

175
// Check confidence in results
176
results.forEach(result => {
177
  if (result.extra && result.extra.confidence) {
178
    console.log(`Confidence: ${result.extra.confidence}`);
179
  }
180
});
181
```
182

183
### Provider-Specific Query Options
184

185
Different providers support various query parameters for enhanced geocoding.
186

187
```javascript { .api }
188
/**
189
 * Google-specific query options
190
 */
191
interface GoogleQuery {
192
  address?: string;
193
  /** Google Place ID for direct lookup */
194
  googlePlaceId?: string;
195
  /** Language override */
196
  language?: string;
197
  /** Region biasing override */
198
  region?: string;
199
  /** Country filter */
200
  country?: string;
201
  /** ZIP code filter */
202
  zipcode?: string;
203
}
204

205
/**
206
 * General address query structure
207
 */
208
interface AddressQuery {
209
  /** Main address string */
210
  address: string;
211
  /** Country filter/preference */
212
  country?: string;
213
  /** ZIP/postal code filter */
214
  zipcode?: string;
215
  /** Language preference */
216
  language?: string;
217
  /** Minimum confidence level */
218
  minConfidence?: number;
219
}
220
```
221

222
**Usage Examples:**
223

224
```javascript
225
// Google Place ID lookup
226
const placeResults = await geocoder.geocode({
227
  googlePlaceId: 'ChIJN1t_tDeuEmsRUsoyG83frY4'
228
});
229

230
// Country and ZIP filtering
231
const filteredResults = await geocoder.geocode({
232
  address: 'Main Street',
233
  country: 'US',
234
  zipcode: '90210'
235
});
236

237
// Language-specific results
238
const germanResults = await geocoder.geocode({
239
  address: 'Brandenburger Tor',
240
  language: 'de'
241
});
242
```
243

244
## Error Handling
245

246
Geocoding operations can fail due to network issues, API limits, or invalid queries.
247

248
```javascript { .api }
249
/**
250
 * Common geocoding errors
251
 */
252
interface GeocodingError extends Error {
253
  /** Error message */
254
  message: string;
255
  /** HTTP status code if applicable */
256
  code?: number;
257
  /** Raw response data */
258
  raw?: any;
259
}
260
```
261

262
**Error Handling Examples:**
263

264
```javascript
265
try {
266
  const results = await geocoder.geocode('invalid address');
267
  if (results.length === 0) {
268
    console.log('No results found');
269
  }
270
} catch (error) {
271
  if (error.message.includes('OVER_QUERY_LIMIT')) {
272
    console.error('API quota exceeded');
273
  } else if (error.message.includes('REQUEST_DENIED')) {
274
    console.error('Invalid API key or permissions');
275
  } else if (error.code) {
276
    console.error(`HTTP Error ${error.code}: ${error.message}`);
277
  } else {
278
    console.error('Geocoding failed:', error.message);
279
  }
280
}
281

282
// Provider-specific error handling
283
geocoder.geocode('test address')
284
  .then(results => {
285
    // Handle zero results
286
    if (results.length === 0) {
287
      console.log('Address not found');
288
      return;
289
    }
290
    console.log('Found:', results[0].formattedAddress);
291
  })
292
  .catch(error => {
293
    console.error('Geocoding error:', error);
294
  });
295
```