0
# Factory and Configuration
1

2
Factory functionality for creating and configuring geocoder instances with different providers and options.
3

4
## Capabilities
5

6
### Main Factory Function
7

8
Creates a geocoder instance with the specified provider and configuration options.
9

10
```javascript { .api }
11
/**
12
 * Creates a geocoder instance with specified provider and options
13
 * @param {string|object} provider - Provider name or options object (if provider is object, it's treated as options)
14
 * @param {object} options - Configuration options for the provider (optional if provider is object)
15
 * @returns {Geocoder} Configured geocoder instance
16
 */
17
function NodeGeocoder(provider?, options?);
18
```
19

20
**Usage Examples:**
21

22
```javascript
23
const NodeGeocoder = require('node-geocoder');
24

25
// Default Google provider
26
const geocoder = NodeGeocoder();
27

28
// Specify provider by name
29
const geocoder = NodeGeocoder('google');
30

31
// Provider with options
32
const geocoder = NodeGeocoder('google', {
33
  apiKey: 'YOUR_API_KEY',
34
  language: 'en',
35
  region: 'us'
36
});
37

38
// Options object only (provider in options)
39
const geocoder = NodeGeocoder({
40
  provider: 'google',
41
  apiKey: 'YOUR_API_KEY',
42
  language: 'en'
43
});
44
```
45

46
### HTTP Adapter Configuration
47

48
Configure the HTTP client used for API requests.
49

50
```javascript { .api }
51
/**
52
 * HTTP adapter options for customizing request behavior
53
 */
54
interface HttpAdapterOptions {
55
  /** Custom fetch implementation */
56
  fetch?: Function;
57
  /** Request timeout in milliseconds */
58
  timeout?: number;
59
  /** Custom headers to include in requests */
60
  headers?: { [key: string]: string };
61
  /** Proxy configuration */
62
  proxy?: string;
63
  /** Additional options passed to fetch */
64
  [key: string]: any;
65
}
66
```
67

68
**Usage Examples:**
69

70
```javascript
71
// Custom headers and timeout
72
const geocoder = NodeGeocoder('google', {
73
  apiKey: 'YOUR_API_KEY',
74
  timeout: 10000,
75
  headers: {
76
    'User-Agent': 'MyApp/1.0'
77
  }
78
});
79

80
// Proxy configuration
81
const geocoder = NodeGeocoder('google', {
82
  apiKey: 'YOUR_API_KEY',
83
  proxy: 'http://proxy.example.com:8080'
84
});
85
```
86

87
### Formatter Configuration
88

89
Configure output formatters to transform geocoding results.
90

91
```javascript { .api }
92
/**
93
 * Formatter configuration options
94
 */
95
interface FormatterOptions {
96
  /** Formatter type: 'gpx' or 'string' */
97
  formatter: 'gpx' | 'string';
98
  /** Pattern for string formatter (required if formatter is 'string') */
99
  formatterPattern?: string;
100
}
101
```
102

103
**Usage Examples:**
104

105
```javascript
106
// GPX formatter
107
const geocoder = NodeGeocoder('google', {
108
  apiKey: 'YOUR_API_KEY',
109
  formatter: 'gpx'
110
});
111

112
// String formatter with custom pattern
113
const geocoder = NodeGeocoder('google', {
114
  apiKey: 'YOUR_API_KEY',
115
  formatter: 'string',
116
  formatterPattern: '%S %n, %c, %P %z'  // Street, Number, City, Country, ZIP
117
});
118
```
119

120
### Provider-Specific Options
121

122
Each provider supports specific configuration options for API keys, language settings, and service-specific parameters.
123

124
```javascript { .api }
125
/**
126
 * Common provider options supported by most providers
127
 */
128
interface CommonProviderOptions {
129
  /** API key for the geocoding service */
130
  apiKey?: string;
131
  /** Language code for localized results */
132
  language?: string;
133
  /** Country/region preference */
134
  country?: string;
135
  /** Maximum number of results to return */
136
  limit?: number;
137
}
138

139
/**
140
 * Google-specific options
141
 */
142
interface GoogleOptions extends CommonProviderOptions {
143
  /** Google client ID for business accounts */
144
  clientId?: string;
145
  /** Region biasing */
146
  region?: string;
147
  /** Exclude partial matches */
148
  excludePartialMatches?: boolean;
149
  /** Channel for premium accounts */
150
  channel?: string;
151
}
152

153
/**
154
 * HERE-specific options
155
 */
156
interface HereOptions extends CommonProviderOptions {
157
  /** HERE app ID (legacy) */
158
  appId?: string;
159
  /** HERE app code (legacy) */
160
  appCode?: string;
161
  /** Political view setting */
162
  politicalView?: string;
163
  /** State preference */
164
  state?: string;
165
  /** Production environment flag */
166
  production?: boolean;
167
}
168
```
169

170
## Error Handling
171

172
The factory validates configuration and throws errors for invalid setups.
173

174
```javascript { .api }
175
/**
176
 * Configuration validation errors
177
 */
178
class ValueError extends Error {
179
  constructor(message: string);
180
  name: 'ValueError';
181
}
182

183
/**
184
 * HTTP-related errors
185
 */
186
class HttpError extends Error {
187
  constructor(message: string, options?: { code?: number });
188
  name: 'HttpError';
189
  code?: number;
190
}
191
```
192

193
**Common Configuration Errors:**
194

195
```javascript
196
// Missing API key for Google business client
197
try {
198
  const geocoder = NodeGeocoder('google', { clientId: 'client123' });
199
} catch (error) {
200
  // Throws: "You must specify a apiKey (privateKey)"
201
}
202

203
// HTTPS required for API key
204
try {
205
  const geocoder = NodeGeocoder('google', {
206
    apiKey: 'key123',
207
    // Using HTTP adapter would cause error
208
  });
209
} catch (error) {
210
  // Throws: "You must use https http adapter"
211
}
212

213
// Invalid provider name
214
try {
215
  const geocoder = NodeGeocoder('invalidprovider');
216
} catch (error) {
217
  // Throws: "No geocoder provider find for : invalidprovider"
218
}
219
```