0
# Node Geocoder
1

2
Node Geocoder is a comprehensive geocoding library for Node.js that supports over 20 different geocoding providers. It enables developers to convert addresses to coordinates (geocoding) and coordinates to addresses (reverse geocoding) using a unified API interface.
3

4
## Package Information
5

6
- **Package Name**: node-geocoder
7
- **Package Type**: npm
8
- **Language**: JavaScript (CommonJS)
9
- **Installation**: `npm install node-geocoder`
10

11
## Core Imports
12

13
```javascript
14
const NodeGeocoder = require('node-geocoder');
15
```
16

17
## Basic Usage
18

19
```javascript
20
const NodeGeocoder = require('node-geocoder');
21

22
// Create geocoder instance with default Google provider
23
const geocoder = NodeGeocoder();
24

25
// Geocode an address
26
geocoder.geocode('29 champs elysée paris')
27
  .then((res) => {
28
    console.log(res);
29
  })
30
  .catch((err) => {
31
    console.log(err);
32
  });
33

34
// Reverse geocode coordinates
35
geocoder.reverse({ lat: 45.767, lon: 4.833 })
36
  .then((res) => {
37
    console.log(res);
38
  })
39
  .catch((err) => {
40
    console.log(err);
41
  });
42
```
43

44
## Architecture
45

46
Node Geocoder follows a factory pattern with these key components:
47

48
- **GeocoderFactory**: Main factory that creates geocoder instances and manages providers
49
- **Geocoder**: Unified wrapper that provides consistent API across all providers
50
- **Provider Classes**: Individual geocoding service implementations (Google, HERE, etc.)
51
- **HTTP Adapter**: Handles HTTP requests using node-fetch
52
- **Formatters**: Transform results into different output formats (GPX, string templates)
53
- **Error Classes**: Standardized error types for HTTP and validation errors
54

55
## Capabilities
56

57
### Factory Function
58

59
Main entry point for creating geocoder instances with provider and configuration options.
60

61
```javascript { .api }
62
/**
63
 * Creates a geocoder instance with specified provider and options
64
 * @param {string|object} provider - Provider name or options object (if object, treated as options with provider inside)
65
 * @param {object} options - Configuration options for the provider (optional if provider is object)
66
 * @returns {Geocoder} Configured geocoder instance
67
 */
68
function NodeGeocoder(provider?, options?);
69
```
70

71
[Factory and Configuration](./factory.md)
72

73
### Geocoding Operations
74

75
Core functionality for converting addresses to coordinates and vice versa.
76

77
```javascript { .api }
78
/**
79
 * Geocode an address or IP to coordinates
80
 * @param {string|object} value - Address string or query object
81
 * @param {function} callback - Optional callback function
82
 * @returns {Promise<GeocodeResult[]>} Array of geocoding results
83
 */
84
geocode(value, callback);
85

86
/**
87
 * Reverse geocode coordinates to address
88
 * @param {object} query - Coordinates object with lat/lon properties
89
 * @param {function} callback - Optional callback function  
90
 * @returns {Promise<GeocodeResult[]>} Array of reverse geocoding results
91
 */
92
reverse(query, callback);
93

94
/**
95
 * Batch geocode multiple addresses (native batch support: aplace, here, tomtom; others use individual calls)
96
 * @param {string[]|object[]} values - Array of addresses or query objects
97
 * @param {function} callback - Optional callback function
98
 * @returns {Promise<BatchResult[]>} Array of batch geocoding results
99
 */
100
batchGeocode(values, callback);
101
```
102

103
[Geocoding Operations](./geocoding.md)
104

105
### Geocoding Providers
106

107
Support for 23 geocoding service providers with provider-specific configuration options.
108

109
```javascript { .api }
110
// Supported provider names
111
type ProviderName = 
112
  | 'google' | 'here' | 'agol' | 'freegeoip' | 'datasciencetoolkit'
113
  | 'openstreetmap' | 'pickpoint' | 'locationiq' | 'mapquest' | 'mapzen'
114
  | 'openmapquest' | 'yandex' | 'geocodio' | 'opencage' | 'nominatimmapquest'
115
  | 'tomtom' | 'virtualearth' | 'smartystreets' | 'teleport' | 'opendatafrance'
116
  | 'mapbox' | 'aplace';
117
```
118

119
[Geocoding Providers](./providers.md)
120

121
### Result Formatting
122

123
Transform geocoding results into different output formats including GPX and custom string templates.
124

125
```javascript { .api }
126
/**
127
 * GPX formatter for converting results to GPX XML format
128
 */
129
interface GpxFormatter {
130
  format(data: GeocodeResult[]): string;
131
}
132

133
/**
134
 * String formatter using pattern templates
135
 */
136
interface StringFormatter {
137
  constructor(pattern: string);
138
  format(data: GeocodeResult[]): string[];
139
}
140
```
141

142
[Result Formatting](./formatters.md)
143

144
## Types
145

146
```javascript { .api }
147
/**
148
 * Standard geocoding result format returned by all providers
149
 */
150
interface GeocodeResult {
151
  /** Full formatted address */
152
  formattedAddress: string;
153
  /** Latitude coordinate */
154
  latitude: number;
155
  /** Longitude coordinate */
156
  longitude: number;
157
  /** Country name */
158
  country?: string;
159
  /** ISO country code */
160
  countryCode?: string;
161
  /** City name */
162
  city?: string;
163
  /** Postal/ZIP code */
164
  zipcode?: string;
165
  /** Street name */
166
  streetName?: string;
167
  /** Street number */
168
  streetNumber?: string;
169
  /** Administrative divisions */
170
  administrativeLevels?: {
171
    level1long?: string;
172
    level1short?: string;
173
    level2long?: string;
174
    level2short?: string;
175
    level3long?: string;
176
    level3short?: string;
177
    level4long?: string;
178
    level4short?: string;
179
    level5long?: string;
180
    level5short?: string;
181
  };
182
  /** Provider-specific additional data */
183
  extra?: {
184
    /** Confidence score (0-1) */
185
    confidence?: number;
186
    /** Provider-specific fields */
187
    [key: string]: any;
188
  };
189
  /** Provider name that generated this result */
190
  provider: string;
191
}
192

193
/**
194
 * Batch geocoding result with error handling
195
 */
196
interface BatchResult {
197
  /** Error if geocoding failed */
198
  error?: Error;
199
  /** Geocoding result if successful */
200
  value?: GeocodeResult[];
201
}
202

203
/**
204
 * Coordinate query object for reverse geocoding
205
 */
206
interface ReverseQuery {
207
  /** Latitude */
208
  lat: number;
209
  /** Longitude */
210
  lon: number;
211
  /** Optional language preference */
212
  language?: string;
213
  /** Provider-specific options */
214
  [key: string]: any;
215
}
216

217
/**
218
 * Address query object for enhanced geocoding
219
 */
220
interface AddressQuery {
221
  /** Address string */
222
  address: string;
223
  /** Country filter */
224
  country?: string;
225
  /** ZIP/postal code filter */
226
  zipcode?: string;
227
  /** Minimum confidence threshold */
228
  minConfidence?: number;
229
  /** Language preference */
230
  language?: string;
231
  /** Provider-specific options */
232
  [key: string]: any;
233
}
234
```