0
# Location and Address Data
1
2
Generate geographical and address information including streets, cities, countries, coordinates, and postal codes with locale-appropriate formatting and realistic regional data.
3
4
## Capabilities
5
6
### Street and Address Generation
7
8
Generate street-level address components with proper formatting for different locales.
9
10
```python { .api }
11
class Address(BaseDataProvider):
12
def street_number(self, maximum: int = 1400) -> str:
13
"""
14
Generate a street number.
15
16
Parameters:
17
- maximum (int): Maximum street number value
18
19
Returns:
20
str: Street number like "123"
21
"""
22
23
def street_name(self) -> str:
24
"""
25
Generate a street name appropriate for the locale.
26
27
Returns:
28
str: Street name like "Main Street", "Oak Avenue"
29
"""
30
31
def street_suffix(self) -> str:
32
"""
33
Generate a street suffix/type.
34
35
Returns:
36
str: Street suffix like "Street", "Avenue", "Boulevard"
37
"""
38
39
def address(self) -> str:
40
"""
41
Generate a complete street address.
42
43
Returns:
44
str: Full address like "123 Main Street"
45
"""
46
```
47
48
### Administrative Divisions
49
50
Generate administrative region data like states, provinces, and regions.
51
52
```python { .api }
53
class Address(BaseDataProvider):
54
def state(self, abbr: bool = False) -> str:
55
"""
56
Generate a state name or abbreviation.
57
58
Parameters:
59
- abbr (bool): Return abbreviation if True
60
61
Returns:
62
str: State like "California" or "CA"
63
"""
64
65
def region(self) -> str:
66
"""
67
Alias for state().
68
69
Returns:
70
str: Region/state name
71
"""
72
73
def province(self) -> str:
74
"""
75
Alias for state().
76
77
Returns:
78
str: Province name
79
"""
80
```
81
82
### Cities and Postal Information
83
84
Generate city names and postal codes appropriate for the locale.
85
86
```python { .api }
87
class Address(BaseDataProvider):
88
def city(self) -> str:
89
"""
90
Generate a city name appropriate for the locale.
91
92
Returns:
93
str: City name like "New York", "London", "Tokyo"
94
"""
95
96
def postal_code(self) -> str:
97
"""
98
Generate a postal code in the locale's format.
99
100
Returns:
101
str: Postal code like "12345", "SW1A 1AA", "1010"
102
"""
103
104
def zip_code(self) -> str:
105
"""
106
Alias for postal_code().
107
108
Returns:
109
str: ZIP/postal code
110
"""
111
```
112
113
### Countries and Territories
114
115
Generate country information with various formatting options.
116
117
```python { .api }
118
class Address(BaseDataProvider):
119
def country(self) -> str:
120
"""
121
Generate a country name.
122
123
Returns:
124
str: Country name like "United States", "Germany"
125
"""
126
127
def country_code(self, code: CountryCode = CountryCode.A2) -> str:
128
"""
129
Generate a country code in various formats.
130
131
Parameters:
132
- code (CountryCode): Format type (A2, A3, or NUMERIC)
133
134
Returns:
135
str: Country code like "US", "USA", or "840"
136
137
Usage:
138
```python
139
address.country_code(CountryCode.A2) # "US"
140
address.country_code(CountryCode.A3) # "USA"
141
address.country_code(CountryCode.NUMERIC) # "840"
142
```
143
"""
144
```
145
146
### Geographic Coordinates
147
148
Generate latitude, longitude, and coordinate data with various formatting options.
149
150
```python { .api }
151
class Address(BaseDataProvider):
152
def latitude(self, dms: bool = False) -> Union[float, str]:
153
"""
154
Generate latitude coordinates.
155
156
Parameters:
157
- dms (bool): Return in Degrees-Minutes-Seconds format if True
158
159
Returns:
160
float or str: Latitude like 40.7128 or "40°42'46.1\"N"
161
"""
162
163
def longitude(self, dms: bool = False) -> Union[float, str]:
164
"""
165
Generate longitude coordinates.
166
167
Parameters:
168
- dms (bool): Return in Degrees-Minutes-Seconds format if True
169
170
Returns:
171
float or str: Longitude like -74.0060 or "74°0'21.6\"W"
172
"""
173
174
def coordinates(self, dms: bool = False) -> dict:
175
"""
176
Generate latitude and longitude pair.
177
178
Parameters:
179
- dms (bool): Return in Degrees-Minutes-Seconds format if True
180
181
Returns:
182
dict: Coordinates like {"latitude": 40.7128, "longitude": -74.0060}
183
"""
184
```
185
186
### Continental and Regional Data
187
188
Generate continent names and international calling codes.
189
190
```python { .api }
191
class Address(BaseDataProvider):
192
def continent(self, code: bool = False) -> str:
193
"""
194
Generate a continent name or code.
195
196
Parameters:
197
- code (bool): Return continent code if True
198
199
Returns:
200
str: Continent like "North America" or "NA"
201
"""
202
203
def calling_code(self) -> str:
204
"""
205
Generate an international calling code.
206
207
Returns:
208
str: Calling code like "+1", "+44", "+81"
209
"""
210
```
211
212
## Usage Examples
213
214
### Basic Address Generation
215
216
```python
217
from mimesis import Address
218
from mimesis.locales import Locale
219
220
address = Address(Locale.EN_US)
221
222
# Generate complete address
223
full_address = {
224
'street': address.address(),
225
'city': address.city(),
226
'state': address.state(),
227
'postal_code': address.postal_code(),
228
'country': address.country()
229
}
230
# Result: {'street': '123 Oak Street', 'city': 'New York', ...}
231
```
232
233
### Localized Address Formats
234
235
```python
236
from mimesis import Address
237
from mimesis.locales import Locale
238
239
# Different locales produce appropriate formats
240
address_us = Address(Locale.EN_US)
241
address_uk = Address(Locale.EN_GB)
242
address_de = Address(Locale.DE)
243
244
us_postal = address_us.postal_code() # "12345"
245
uk_postal = address_uk.postal_code() # "SW1A 1AA"
246
de_postal = address_de.postal_code() # "10115"
247
```
248
249
### Geographic Coordinates
250
251
```python
252
from mimesis import Address
253
254
address = Address()
255
256
# Decimal coordinates
257
lat_decimal = address.latitude() # 40.7128
258
lng_decimal = address.longitude() # -74.0060
259
260
# Degrees-Minutes-Seconds format
261
lat_dms = address.latitude(dms=True) # "40°42'46.1\"N"
262
lng_dms = address.longitude(dms=True) # "74°0'21.6\"W"
263
264
# Coordinate pair
265
coords = address.coordinates() # {"latitude": 40.7128, "longitude": -74.0060}
266
coords_dms = address.coordinates(dms=True) # DMS format pair
267
```
268
269
### Country Information
270
271
```python
272
from mimesis import Address
273
from mimesis.enums import CountryCode
274
275
address = Address()
276
277
# Different country code formats
278
country_name = address.country() # "United States"
279
country_a2 = address.country_code(CountryCode.A2) # "US"
280
country_a3 = address.country_code(CountryCode.A3) # "USA"
281
country_numeric = address.country_code(CountryCode.NUMERIC) # "840"
282
283
# Calling code
284
calling_code = address.calling_code() # "+1"
285
```
286
287
### Address Variations
288
289
```python
290
from mimesis import Address
291
292
address = Address(Locale.EN_US)
293
294
# State formats
295
state_full = address.state(abbr=False) # "California"
296
state_abbr = address.state(abbr=True) # "CA"
297
298
# Continental information
299
continent_name = address.continent(code=False) # "North America"
300
continent_code = address.continent(code=True) # "NA"
301
```
302
303
### Complete Location Profile
304
305
```python
306
from mimesis import Address
307
from mimesis.enums import CountryCode
308
309
def generate_location_profile(locale: Locale):
310
address = Address(locale)
311
312
return {
313
'address': {
314
'street': address.address(),
315
'city': address.city(),
316
'state': address.state(),
317
'postal_code': address.postal_code(),
318
},
319
'country': {
320
'name': address.country(),
321
'code_a2': address.country_code(CountryCode.A2),
322
'code_a3': address.country_code(CountryCode.A3),
323
'calling_code': address.calling_code(),
324
},
325
'coordinates': address.coordinates(),
326
'coordinates_dms': address.coordinates(dms=True),
327
'continent': {
328
'name': address.continent(),
329
'code': address.continent(code=True),
330
}
331
}
332
333
# Generate profiles for different regions
334
us_location = generate_location_profile(Locale.EN_US)
335
uk_location = generate_location_profile(Locale.EN_GB)
336
jp_location = generate_location_profile(Locale.JA)
337
```
338
339
### Bulk Address Generation
340
341
```python
342
from mimesis import Address
343
344
address = Address(Locale.EN_US)
345
346
# Generate multiple addresses
347
addresses = []
348
for _ in range(10):
349
addr = {
350
'id': len(addresses) + 1,
351
'street_number': address.street_number(),
352
'street_name': address.street_name(),
353
'street_suffix': address.street_suffix(),
354
'city': address.city(),
355
'state': address.state(abbr=True),
356
'postal_code': address.postal_code(),
357
'coordinates': address.coordinates()
358
}
359
addresses.append(addr)
360
```