ideal-postcodes 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (11) hide show
  1. ideal_postcodes/__init__.py +27 -0
  2. ideal_postcodes/_transport.py +194 -0
  3. ideal_postcodes/client.py +1321 -0
  4. ideal_postcodes/errors.py +81 -0
  5. ideal_postcodes/py.typed +0 -0
  6. ideal_postcodes/requests.py +70 -0
  7. ideal_postcodes/types.py +6939 -0
  8. ideal_postcodes-0.1.0.dist-info/METADATA +121 -0
  9. ideal_postcodes-0.1.0.dist-info/RECORD +11 -0
  10. ideal_postcodes-0.1.0.dist-info/WHEEL +4 -0
  11. ideal_postcodes-0.1.0.dist-info/licenses/LICENSE +1 -0
ideal_postcodes/client.py ADDED
@@ -0,0 +1,1321 @@
1
+ """Address and key methods. Generated by sdk-tools/python/generate.py."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import Any, Literal, cast, overload
6
+
7
+ from . import requests, types
8
+ from ._transport import Transport, check_inputs, fields, segment, validate
9
+
10
+ # Spec constraints per method, checked before any request.
11
+ INPUTS: dict[str, dict[str, Any]] = {
12
+ "postcodes": {
13
+ "postcode": {"type": "string"},
14
+ "filter": {"type": "string"},
15
+ "page": {"type": "integer", "minimum": 0, "maximum": 100},
16
+ "tags": {"type": "string"},
17
+ "dataset": {"type": "array", "items": {"type": "string"}},
18
+ "context": {"type": "string"},
19
+ },
20
+ "key_availability": {"key": {"type": "string"}},
21
+ "key_details": {"key": {"type": "string"}, "user_token": {"type": "string"}},
22
+ "update_key_details": {
23
+ "key": {"type": "string"},
24
+ "user_token": {"type": "string"},
25
+ "name": {"type": "string", "maxLength": 32, "pattern": "^(\\w|\\s){0,32}$"},
26
+ "daily_limit": {"type": "object", "properties": {"limit": {"type": "integer", "nullable": True, "minimum": 0}}},
27
+ "monthly_limit": {
28
+ "type": "object",
29
+ "properties": {"limit": {"type": "integer", "nullable": True, "minimum": 0}},
30
+ },
31
+ "individual_limit": {
32
+ "type": "object",
33
+ "properties": {"limit": {"type": "integer", "nullable": True, "minimum": 0}},
34
+ },
35
+ "allowed_urls": {"type": "array", "items": {"type": "string", "maxLength": 256, "pattern": "^[^\\s]+$"}},
36
+ "redact_days": {"type": "integer", "minimum": 0, "maximum": 1095},
37
+ "notifications": {
38
+ "type": "object",
39
+ "properties": {
40
+ "emails": {"type": "array", "items": {"type": "string", "pattern": "^\\S{1,100}@\\S{1,100}$"}},
41
+ "enabled": {"type": "boolean"},
42
+ "balance_threshold": {"type": "integer", "nullable": True, "minimum": 0},
43
+ "no_balance": {"type": "boolean"},
44
+ "limit_reached": {"type": "boolean"},
45
+ },
46
+ },
47
+ "ip_forwarding": {"type": "boolean"},
48
+ "datasets": {
49
+ "type": "object",
50
+ "properties": {
51
+ "pafa": {"type": "boolean"},
52
+ "pafw": {"type": "boolean"},
53
+ "usps": {"type": "boolean"},
54
+ "hereap": {"type": "boolean"},
55
+ "herehk": {"type": "boolean"},
56
+ "herei": {"type": "boolean"},
57
+ "herem": {"type": "boolean"},
58
+ "heremea": {"type": "boolean"},
59
+ "heremeas": {"type": "boolean"},
60
+ "herena": {"type": "boolean"},
61
+ "hereo": {"type": "boolean"},
62
+ "heresa": {"type": "boolean"},
63
+ "heret": {"type": "boolean"},
64
+ "hereee": {"type": "boolean"},
65
+ "herewe": {"type": "boolean"},
66
+ "phone": {"type": "boolean"},
67
+ "email": {"type": "boolean"},
68
+ "gnaf": {"type": "boolean"},
69
+ "kadaster": {"type": "boolean"},
70
+ "kartverket": {"type": "boolean"},
71
+ "sdfi": {"type": "boolean"},
72
+ "cannar": {"type": "boolean"},
73
+ "fodbosa": {"type": "boolean"},
74
+ "mois": {"type": "boolean"},
75
+ "upujp": {"type": "boolean"},
76
+ "bev": {"type": "boolean"},
77
+ "ban": {"type": "boolean"},
78
+ "swt": {"type": "boolean"},
79
+ "ab": {"type": "boolean"},
80
+ "abp": {"type": "boolean"},
81
+ "nip": {"type": "boolean"},
82
+ "gbrcleanse": {"type": "boolean"},
83
+ "uspscleanse": {"type": "boolean"},
84
+ },
85
+ },
86
+ },
87
+ "key_usage": {
88
+ "key": {"type": "string"},
89
+ "user_token": {"type": "string"},
90
+ "start": {"type": "integer", "minimum": 0},
91
+ "end": {"type": "integer", "minimum": 0},
92
+ "tags": {"type": "string"},
93
+ "licensee": {"type": "string"},
94
+ },
95
+ "key_logs": {
96
+ "key": {"type": "string"},
97
+ "user_token": {"type": "string"},
98
+ "start": {"type": "integer", "minimum": 0},
99
+ "end": {"type": "integer", "minimum": 0},
100
+ "licensee": {"type": "string"},
101
+ },
102
+ "address_cleanse": {
103
+ "tags": {"type": "string"},
104
+ "context": {"type": "string"},
105
+ "query": {"type": "string"},
106
+ "postcode": {"type": "string"},
107
+ "post_town": {"type": "string"},
108
+ "county": {"type": "string"},
109
+ },
110
+ "find_address": {
111
+ "query": {"type": "string", "maxLength": 150},
112
+ "dataset": {"type": "array", "items": {"type": "string"}},
113
+ "context": {"type": "string"},
114
+ "limit": {"type": "integer", "minimum": 1, "maximum": 100},
115
+ "bias_lonlat": {"type": "string"},
116
+ "bias_ip": {"type": "string"},
117
+ "box": {"type": "string"},
118
+ "postcode_outward": {"type": "string"},
119
+ "postcode": {"type": "string"},
120
+ "postcode_area": {"type": "string"},
121
+ "postcode_sector": {"type": "string"},
122
+ "post_town": {"type": "string"},
123
+ "uprn": {"type": "integer"},
124
+ "country": {"type": "string"},
125
+ "postcode_type": {"type": "string"},
126
+ "su_organisation_indicator": {"type": "string"},
127
+ "bias_postcode_outward": {"type": "string"},
128
+ "bias_postcode": {"type": "string"},
129
+ "bias_postcode_area": {"type": "string"},
130
+ "bias_postcode_sector": {"type": "string"},
131
+ "bias_post_town": {"type": "string"},
132
+ "bias_thoroughfare": {"type": "string"},
133
+ "bias_country": {"type": "string"},
134
+ "postal_code": {"type": "string"},
135
+ "postal_code_2": {"type": "string"},
136
+ "postal_code_3": {"type": "string"},
137
+ "city": {"type": "string"},
138
+ "state": {"type": "string"},
139
+ "state_code": {"type": "string"},
140
+ "bias_postal_code": {"type": "string"},
141
+ "bias_postal_code_2": {"type": "string"},
142
+ "bias_postal_code_3": {"type": "string"},
143
+ "bias_city": {"type": "string"},
144
+ "bias_state": {"type": "string"},
145
+ "bias_state_code": {"type": "string"},
146
+ "is_pobox": {"type": "string"},
147
+ "is_business": {"type": "string"},
148
+ },
149
+ "resolve_address": {"address": {"type": "string"}, "tags": {"type": "string"}},
150
+ "addresses": {
151
+ "query": {"type": "string"},
152
+ "limit": {"type": "integer", "minimum": 1, "maximum": 100},
153
+ "page": {"type": "integer", "minimum": 0, "maximum": 100},
154
+ "filter": {"type": "string"},
155
+ "lon": {"type": "number", "minimum": -180, "maximum": 180},
156
+ "lat": {"type": "number", "minimum": -90, "maximum": 90},
157
+ "postcode_outward": {"type": "string"},
158
+ "postcode": {"type": "string"},
159
+ "postcode_area": {"type": "string"},
160
+ "postcode_sector": {"type": "string"},
161
+ "post_town": {"type": "string"},
162
+ "uprn": {"type": "integer"},
163
+ "country": {"type": "string"},
164
+ "postcode_type": {"type": "string"},
165
+ "su_organisation_indicator": {"type": "string"},
166
+ "box": {"type": "string"},
167
+ "bias_postcode_outward": {"type": "string"},
168
+ "bias_postcode": {"type": "string"},
169
+ "bias_postcode_area": {"type": "string"},
170
+ "bias_postcode_sector": {"type": "string"},
171
+ "bias_post_town": {"type": "string"},
172
+ "bias_thoroughfare": {"type": "string"},
173
+ "bias_country": {"type": "string"},
174
+ "bias_lonlat": {"type": "string"},
175
+ "tags": {"type": "string"},
176
+ "dataset": {"type": "array", "items": {"type": "string"}},
177
+ },
178
+ "find_place": {
179
+ "query": {"type": "string"},
180
+ "country_iso": {"type": "string"},
181
+ "bias_country_iso": {"type": "string"},
182
+ "bias_lonlat": {"type": "string"},
183
+ "bias_ip": {"type": "string"},
184
+ },
185
+ "resolve_place": {"place": {"type": "string"}, "tags": {"type": "string"}},
186
+ "list_licensees": {
187
+ "key": {"type": "string"},
188
+ "starting_after": {"type": "integer"},
189
+ "user_token": {"type": "string"},
190
+ "limit": {"type": "integer", "minimum": 1, "maximum": 100},
191
+ "query": {"type": "string"},
192
+ },
193
+ "create_licensee": {
194
+ "key": {"type": "string"},
195
+ "user_token": {"type": "string"},
196
+ "name": {"type": "string"},
197
+ "address": {"type": "string"},
198
+ "postcode": {"type": "string"},
199
+ "whitelist": {"type": "array", "items": {"type": "string"}},
200
+ "daily": {"type": "object", "properties": {"limit": {"type": "number", "nullable": True, "minimum": 0}}},
201
+ },
202
+ "retrieve_licensee": {"key": {"type": "string"}, "licensee": {"type": "string"}, "user_token": {"type": "string"}},
203
+ "delete_licensee": {"key": {"type": "string"}, "licensee": {"type": "string"}, "user_token": {"type": "string"}},
204
+ "update_licensee": {
205
+ "key": {"type": "string"},
206
+ "licensee": {"type": "string"},
207
+ "user_token": {"type": "string"},
208
+ "name": {"type": "string"},
209
+ "address": {"type": "string"},
210
+ "postcode": {"type": "string"},
211
+ "whitelist": {"type": "array", "items": {"type": "string"}},
212
+ "daily": {"type": "object", "properties": {"limit": {"type": "number", "nullable": True, "minimum": 0}}},
213
+ },
214
+ "regenerate_licensee_key": {
215
+ "key": {"type": "string"},
216
+ "licensee": {"type": "string"},
217
+ "user_token": {"type": "string"},
218
+ },
219
+ "list_configs": {"key": {"type": "string"}, "user_token": {"type": "string"}},
220
+ "create_config": {
221
+ "key": {"type": "string"},
222
+ "user_token": {"type": "string"},
223
+ "name": {"type": "string", "minLength": 1, "maxLength": 32},
224
+ "payload": {"type": "string", "minLength": 0, "maxLength": 65536},
225
+ },
226
+ "retrieve_config": {"key": {"type": "string"}, "config": {"type": "string"}},
227
+ "delete_config": {"key": {"type": "string"}, "config": {"type": "string"}, "user_token": {"type": "string"}},
228
+ "update_config": {
229
+ "key": {"type": "string"},
230
+ "config": {"type": "string"},
231
+ "user_token": {"type": "string"},
232
+ "payload": {"type": "string", "minLength": 0, "maxLength": 65536},
233
+ },
234
+ "email_validation": {"query": {"type": "string"}, "tags": {"type": "string"}},
235
+ "phone_number_validation": {
236
+ "query": {"type": "string"},
237
+ "current_carrier": {"type": "string"},
238
+ "tags": {"type": "string"},
239
+ },
240
+ }
241
+
242
+
243
+ class IdealPostcodes(Transport):
244
+ """IdealPostcodes address lookups and key APIs with explicit parameters and validated response models."""
245
+
246
+ @overload
247
+ def postcodes(
248
+ self,
249
+ postcode: str,
250
+ *,
251
+ filter: None = None,
252
+ page: int | None = None,
253
+ tags: str | None = None,
254
+ dataset: list[types.Dataset] | None = None,
255
+ context: str | None = None,
256
+ ) -> types.PostcodesResult: ...
257
+
258
+ @overload
259
+ def postcodes(
260
+ self,
261
+ postcode: str,
262
+ *,
263
+ filter: str,
264
+ page: int | None = None,
265
+ tags: str | None = None,
266
+ dataset: list[types.Dataset] | None = None,
267
+ context: str | None = None,
268
+ ) -> list[dict[str, Any]]: ...
269
+
270
+ def postcodes(
271
+ self,
272
+ postcode: str,
273
+ *,
274
+ filter: str | None = None,
275
+ page: int | None = None,
276
+ tags: str | None = None,
277
+ dataset: list[types.Dataset] | None = None,
278
+ context: str | None = None,
279
+ ) -> types.PostcodesResult | list[dict[str, Any]]:
280
+ """Lookup Postcode.
281
+
282
+ GET /postcodes/{postcode}. Returns the result payload.
283
+ postcode: Required. Postcode to retrieve
284
+ filter: Optional. Comma separated whitelist of address elements to return.
285
+ page: Optional. 0 indexed indicator of the page of results to receive. Virtually all postcode results are returned on page 0. default=0; minimum=0; maximum=100
286
+ tags: Optional. A comma separated list of tags to query over.
287
+ dataset: Optional. Comma-separated list of datasets to search within.
288
+ context: Optional. Limits search results, typically within a country.
289
+
290
+ Raises APIError, TransportError or ProtocolError on failure.
291
+ """
292
+ check_inputs(
293
+ INPUTS["postcodes"],
294
+ postcode=postcode,
295
+ filter=filter,
296
+ page=page,
297
+ tags=tags,
298
+ dataset=dataset,
299
+ context=context,
300
+ )
301
+ return cast(
302
+ types.PostcodesResult | list[dict[str, Any]],
303
+ validate(
304
+ (list[dict[str, Any]] if filter is not None else types.PostcodesResult),
305
+ self._request(
306
+ "GET",
307
+ f"/postcodes/{segment(postcode)}",
308
+ result_shape="array",
309
+ query={"filter": filter, "page": page, "tags": tags, "dataset": dataset, "context": context},
310
+ ),
311
+ ),
312
+ )
313
+
314
+ def key_availability(self, key: str) -> types.KeyAvailabilityResult:
315
+ """Availability.
316
+
317
+ GET /keys/{key}. Returns the result payload.
318
+ key: Required. The API Key to retrieve. Begins `ak_`.
319
+
320
+ Raises APIError, TransportError or ProtocolError on failure.
321
+ """
322
+ check_inputs(INPUTS["key_availability"], key=key)
323
+ return cast(
324
+ types.KeyAvailabilityResult,
325
+ validate(types.KeyAvailabilityResult, self._request("GET", f"/keys/{segment(key)}")),
326
+ )
327
+
328
+ def key_details(self, key: str, *, user_token: str) -> types.KeyDetailsResult:
329
+ """Details.
330
+
331
+ GET /keys/{key}/details. Returns the result payload.
332
+ key: Required. The API Key to retrieve. Begins `ak_`.
333
+ user_token: Required. A secret key used to manage your account and API Keys. It was previously called the user token.
334
+
335
+ Raises APIError, TransportError or ProtocolError on failure.
336
+ """
337
+ check_inputs(INPUTS["key_details"], key=key, user_token=user_token)
338
+ return cast(
339
+ types.KeyDetailsResult,
340
+ validate(
341
+ types.KeyDetailsResult, self._request("GET", f"/keys/{segment(key)}/details", user_token=user_token)
342
+ ),
343
+ )
344
+
345
+ def update_key_details(
346
+ self,
347
+ key: str,
348
+ *,
349
+ user_token: str,
350
+ name: str | None = None,
351
+ daily_limit: requests.UpdateKeyDetailsDailyLimit | None = None,
352
+ monthly_limit: requests.UpdateKeyDetailsMonthlyLimit | None = None,
353
+ individual_limit: requests.UpdateKeyDetailsIndividualLimit | None = None,
354
+ allowed_urls: list[str] | None = None,
355
+ redact_days: int | None = None,
356
+ notifications: requests.UpdateKeyDetailsNotifications | None = None,
357
+ ip_forwarding: bool | None = None,
358
+ datasets: requests.UpdateKeyDetailsDatasets | None = None,
359
+ ) -> types.UpdateKeyDetailsResult:
360
+ """Update Details.
361
+
362
+ PUT /keys/{key}/details. Returns the result payload.
363
+ key: Required. The API Key to retrieve. Begins `ak_`.
364
+ user_token: Required. A secret key used to manage your account and API Keys. It was previously called the user token.
365
+ name: Optional. A name for the key maxLength=32
366
+ daily_limit: Optional.
367
+ monthly_limit: Optional.
368
+ individual_limit: Optional.
369
+ allowed_urls: Optional. A list of allowed URLs. An empty list disables the check. Up to 10 allowed.
370
+ redact_days: Optional. Number of days to preserve personal data stored in your key usage history. Set to 0 to prevent personal data storage default=28; minimum=0; maximum=1095
371
+ notifications: Optional.
372
+ ip_forwarding: Optional. Accept IP addresses forwarded in the `IDPC-Source-IP` header default=False
373
+ datasets: Optional. Indicates which datasets are available and added by default to the address responses
374
+
375
+ Raises APIError, TransportError or ProtocolError on failure.
376
+ """
377
+ check_inputs(
378
+ INPUTS["update_key_details"],
379
+ key=key,
380
+ user_token=user_token,
381
+ name=name,
382
+ daily_limit=daily_limit,
383
+ monthly_limit=monthly_limit,
384
+ individual_limit=individual_limit,
385
+ allowed_urls=allowed_urls,
386
+ redact_days=redact_days,
387
+ notifications=notifications,
388
+ ip_forwarding=ip_forwarding,
389
+ datasets=datasets,
390
+ )
391
+ return cast(
392
+ types.UpdateKeyDetailsResult,
393
+ validate(
394
+ types.UpdateKeyDetailsResult,
395
+ self._request(
396
+ "PUT",
397
+ f"/keys/{segment(key)}/details",
398
+ user_token=user_token,
399
+ body=fields(
400
+ {
401
+ "name": name,
402
+ "daily_limit": daily_limit,
403
+ "monthly_limit": monthly_limit,
404
+ "individual_limit": individual_limit,
405
+ "allowed_urls": allowed_urls,
406
+ "redact_days": redact_days,
407
+ "notifications": notifications,
408
+ "ip_forwarding": ip_forwarding,
409
+ "datasets": datasets,
410
+ }
411
+ ),
412
+ ),
413
+ ),
414
+ )
415
+
416
+ def key_usage(
417
+ self,
418
+ key: str,
419
+ *,
420
+ user_token: str,
421
+ start: int | None = None,
422
+ end: int | None = None,
423
+ tags: str | None = None,
424
+ licensee: str | None = None,
425
+ ) -> types.KeyUsageResult:
426
+ """Usage Stats.
427
+
428
+ GET /keys/{key}/usage. Returns the result payload.
429
+ key: Required. The API Key to retrieve. Begins `ak_`.
430
+ user_token: Required. A secret key used to manage your account and API Keys. It was previously called the user token.
431
+ start: Optional. A start date/time in the form of a UNIX Timestamp in milliseconds. E.g. `1418556452651` minimum=0
432
+ end: Optional. An end date/time in the form of a UNIX Timestamp in milliseconds. E.g. `1418556477882` minimum=0
433
+ tags: Optional. A comma separated list of tags to query over.
434
+ licensee: Optional. Uniquely identifies a licensee.
435
+
436
+ Raises APIError, TransportError or ProtocolError on failure.
437
+ """
438
+ check_inputs(
439
+ INPUTS["key_usage"], key=key, user_token=user_token, start=start, end=end, tags=tags, licensee=licensee
440
+ )
441
+ return cast(
442
+ types.KeyUsageResult,
443
+ validate(
444
+ types.KeyUsageResult,
445
+ self._request(
446
+ "GET",
447
+ f"/keys/{segment(key)}/usage",
448
+ user_token=user_token,
449
+ query={"start": start, "end": end, "tags": tags, "licensee": licensee},
450
+ ),
451
+ ),
452
+ )
453
+
454
+ def key_logs(
455
+ self,
456
+ key: str,
457
+ *,
458
+ user_token: str,
459
+ start: int | None = None,
460
+ end: int | None = None,
461
+ licensee: str | None = None,
462
+ ) -> str:
463
+ """Logs (CSV).
464
+
465
+ GET /keys/{key}/lookups. Returns CSV text.
466
+ key: Required. The API Key to retrieve. Begins `ak_`.
467
+ user_token: Required. A secret key used to manage your account and API Keys. It was previously called the user token.
468
+ start: Optional. A start date/time in the form of a UNIX Timestamp in milliseconds. E.g. `1418556452651` minimum=0
469
+ end: Optional. An end date/time in the form of a UNIX Timestamp in milliseconds. E.g. `1418556477882` minimum=0
470
+ licensee: Optional. Uniquely identifies a licensee.
471
+
472
+ Raises APIError, TransportError or ProtocolError on failure.
473
+ """
474
+ check_inputs(INPUTS["key_logs"], key=key, user_token=user_token, start=start, end=end, licensee=licensee)
475
+ return cast(
476
+ str,
477
+ self._request(
478
+ "GET",
479
+ f"/keys/{segment(key)}/lookups",
480
+ result_shape="csv",
481
+ user_token=user_token,
482
+ query={"start": start, "end": end, "licensee": licensee},
483
+ ),
484
+ )
485
+
486
+ def address_cleanse(
487
+ self,
488
+ *,
489
+ query: str,
490
+ tags: str | None = None,
491
+ context: str | None = None,
492
+ postcode: str | None = None,
493
+ post_town: str | None = None,
494
+ county: str | None = None,
495
+ ) -> types.AddressCleanseResult:
496
+ """Cleanse Address.
497
+
498
+ POST /cleanse/addresses. Returns the result payload.
499
+ tags: Optional. A comma separated list of tags to query over.
500
+ context: Optional. Identify the country of the address to cleanse. Defaults to UK (GBR)
501
+ query: Required. Freeform address input to cleanse
502
+ postcode: Optional. Optionally specify the postal code for the address.
503
+ post_town: Optional. Optionally specify the city or town of the address.
504
+ county: Optional. Optionally specify the county of the address.
505
+
506
+ Raises APIError, TransportError or ProtocolError on failure.
507
+ """
508
+ check_inputs(
509
+ INPUTS["address_cleanse"],
510
+ query=query,
511
+ tags=tags,
512
+ context=context,
513
+ postcode=postcode,
514
+ post_town=post_town,
515
+ county=county,
516
+ )
517
+ return cast(
518
+ types.AddressCleanseResult,
519
+ validate(
520
+ types.AddressCleanseResult,
521
+ self._request(
522
+ "POST",
523
+ "/cleanse/addresses",
524
+ query={"tags": tags, "context": context},
525
+ body=fields({"query": query, "postcode": postcode, "post_town": post_town, "county": county}),
526
+ ),
527
+ ),
528
+ )
529
+
530
+ def find_address(
531
+ self,
532
+ *,
533
+ query: str,
534
+ dataset: list[types.Dataset] | None = None,
535
+ context: str | None = None,
536
+ limit: int | None = None,
537
+ bias_lonlat: str | None = None,
538
+ bias_ip: Literal["true"] | str | None = None,
539
+ box: str | None = None,
540
+ postcode_outward: str | None = None,
541
+ postcode: str | None = None,
542
+ postcode_area: str | None = None,
543
+ postcode_sector: str | None = None,
544
+ post_town: str | None = None,
545
+ uprn: int | None = None,
546
+ country: str | None = None,
547
+ postcode_type: str | None = None,
548
+ su_organisation_indicator: str | None = None,
549
+ bias_postcode_outward: str | None = None,
550
+ bias_postcode: str | None = None,
551
+ bias_postcode_area: str | None = None,
552
+ bias_postcode_sector: str | None = None,
553
+ bias_post_town: str | None = None,
554
+ bias_thoroughfare: str | None = None,
555
+ bias_country: str | None = None,
556
+ postal_code: str | None = None,
557
+ postal_code_2: str | None = None,
558
+ postal_code_3: str | None = None,
559
+ city: str | None = None,
560
+ state: str | None = None,
561
+ state_code: str | None = None,
562
+ bias_postal_code: str | None = None,
563
+ bias_postal_code_2: str | None = None,
564
+ bias_postal_code_3: str | None = None,
565
+ bias_city: str | None = None,
566
+ bias_state: str | None = None,
567
+ bias_state_code: str | None = None,
568
+ is_pobox: Literal["true", "false"] | str | None = None,
569
+ is_business: Literal["true", "false"] | str | None = None,
570
+ ) -> types.FindAddressResult:
571
+ """Find Address.
572
+
573
+ GET /autocomplete/addresses. Returns the result payload.
574
+ query: Required. The partial address string entered by the user to autocomplete. maxLength=150
575
+ dataset: Optional. Comma-separated list of datasets to search within.
576
+ context: Optional. Limits search results, typically within a country.
577
+ limit: Optional. Specifies the maximum number of records to retrieve. default=10; minimum=1; maximum=100
578
+ bias_lonlat: Optional. Bias search to a geospatial circle determined by an origin and radius in metres. Max radius is `50000`. Uses the format bias_lonlat=[longitude],[latitude],[radius in metres]. Only one geospatial bias may be provided.
579
+ bias_ip: Optional. Biases search based on approximate geolocation of IP address. enum=['true']
580
+ box: Optional. Restrict search to a geospatial box determined by the 'top-left' and 'bottom-right' geolocations.
581
+ postcode_outward: Optional. Restrict result set to addresses with a matching outward code.
582
+ postcode: Optional. **Filter by postcode** Restrict result set to matching postcodes only. Can be combined with query to perform a postcode and building number or name search.
583
+ postcode_area: Optional. Postcode area represents the first one or two non-numeric characters of a postcode. E.g. the postcode area of `SW1A 2AA` is `SW`.
584
+ postcode_sector: Optional. Postcode sector is the outward code plus first numeric of the inward code. E.g. postcode sector of `SW1A 2AA` is `SW1A 2`
585
+ post_town: Optional. Restrict addresses to matching town, city or other locality identifier.
586
+ uprn: Optional. Does not accept comma separated terms. Only a single term is permitted.
587
+ country: Optional. Filters by country name.
588
+ postcode_type: Optional. Useful for separating organisational and residential addresses.
589
+ su_organisation_indicator: Optional. Useful for separating organisational and residential addresses.
590
+ bias_postcode_outward: Optional. **Bias by Outward Code** Boosts addresses with a matching outward code. The outward code is the first half of a postcode. For instance, the outward code of `SW1A 2AA` is `SW1A`.
591
+ bias_postcode: Optional. **Bias by postcode** Boost addresses which match postcode. Can be combined with query to perform a postcode and building number or name search.
592
+ bias_postcode_area: Optional. Boosts if the first one or two non-numeric characters of a postcode match
593
+ bias_postcode_sector: Optional. Boost postcode sector matches. The postcode sector comprises the outward code plus first numeric of the inward code.
594
+ bias_post_town: Optional. Biases results to matching town, city or other locality name.
595
+ bias_thoroughfare: Optional. Bias by street or thoroughfare name.
596
+ bias_country: Optional. Possible values are England, Scotland, Wales, Northern Ireland, Jersey, Guernsey and Isle of Man.
597
+ postal_code: Optional. Restrict results to addresses with a matching full postal code. Case, spaces and hyphens are ignored. For US addresses the full postal code is the nine digit ZIP+4 (`941021234`); filter on `postal_code_3` for a five digit ZIP. For UK addresses use `postcode`.
598
+ postal_code_2: Optional. Restrict results to addresses whose postal code starts with the given segment. For US addresses this is the three digit ZIP prefix (sectional center), e.g. `941` for San Francisco.
599
+ postal_code_3: Optional. Restrict results to addresses with a matching short postal code. For US addresses this is the five digit ZIP code.
600
+ city: Optional. Restrict results to addresses in the named city, town or locality. Case, spaces and accents are ignored, so `San Francisco` and `sanfrancisco` match the same addresses. For UK addresses use `post_town`.
601
+ state: Optional. Restrict results to addresses in the named state, province or region, e.g. `California`. Case and spaces are ignored.
602
+ state_code: Optional. Restrict results to addresses with a matching state or region code, e.g. the two letter USPS state abbreviation `CA`. Case is ignored.
603
+ bias_postal_code: Optional. Boost addresses with a matching full postal code (nine digit ZIP+4 for US addresses). Unmatched addresses still appear, ranked lower.
604
+ bias_postal_code_2: Optional. Boost addresses whose postal code starts with the given segment (three digit ZIP prefix for US addresses).
605
+ bias_postal_code_3: Optional. Boost addresses with a matching short postal code (five digit ZIP for US addresses).
606
+ bias_city: Optional. Boost addresses in the named city, town or locality. Case, spaces and accents are ignored. For UK addresses use `bias_posttown`.
607
+ bias_state: Optional. Boost addresses in the named state, province or region.
608
+ bias_state_code: Optional. Boost addresses with a matching state or region code, e.g. `CA`.
609
+ is_pobox: Optional. `true` restricts results to PO Box addresses; `false` excludes them. For US addresses this is derived from the USPS record type (`P`). enum=['true', 'false']
610
+ is_business: Optional. `true` restricts results to business addresses; `false` excludes them. For US addresses this is derived from the USPS record type (`F`, a firm record). enum=['true', 'false']
611
+
612
+ Raises APIError, TransportError or ProtocolError on failure.
613
+ """
614
+ check_inputs(
615
+ INPUTS["find_address"],
616
+ query=query,
617
+ dataset=dataset,
618
+ context=context,
619
+ limit=limit,
620
+ bias_lonlat=bias_lonlat,
621
+ bias_ip=bias_ip,
622
+ box=box,
623
+ postcode_outward=postcode_outward,
624
+ postcode=postcode,
625
+ postcode_area=postcode_area,
626
+ postcode_sector=postcode_sector,
627
+ post_town=post_town,
628
+ uprn=uprn,
629
+ country=country,
630
+ postcode_type=postcode_type,
631
+ su_organisation_indicator=su_organisation_indicator,
632
+ bias_postcode_outward=bias_postcode_outward,
633
+ bias_postcode=bias_postcode,
634
+ bias_postcode_area=bias_postcode_area,
635
+ bias_postcode_sector=bias_postcode_sector,
636
+ bias_post_town=bias_post_town,
637
+ bias_thoroughfare=bias_thoroughfare,
638
+ bias_country=bias_country,
639
+ postal_code=postal_code,
640
+ postal_code_2=postal_code_2,
641
+ postal_code_3=postal_code_3,
642
+ city=city,
643
+ state=state,
644
+ state_code=state_code,
645
+ bias_postal_code=bias_postal_code,
646
+ bias_postal_code_2=bias_postal_code_2,
647
+ bias_postal_code_3=bias_postal_code_3,
648
+ bias_city=bias_city,
649
+ bias_state=bias_state,
650
+ bias_state_code=bias_state_code,
651
+ is_pobox=is_pobox,
652
+ is_business=is_business,
653
+ )
654
+ return cast(
655
+ types.FindAddressResult,
656
+ validate(
657
+ types.FindAddressResult,
658
+ self._request(
659
+ "GET",
660
+ "/autocomplete/addresses",
661
+ query={
662
+ "query": query,
663
+ "dataset": dataset,
664
+ "context": context,
665
+ "limit": limit,
666
+ "bias_lonlat": bias_lonlat,
667
+ "bias_ip": bias_ip,
668
+ "box": box,
669
+ "postcode_outward": postcode_outward,
670
+ "postcode": postcode,
671
+ "postcode_area": postcode_area,
672
+ "postcode_sector": postcode_sector,
673
+ "post_town": post_town,
674
+ "uprn": uprn,
675
+ "country": country,
676
+ "postcode_type": postcode_type,
677
+ "su_organisation_indicator": su_organisation_indicator,
678
+ "bias_postcode_outward": bias_postcode_outward,
679
+ "bias_postcode": bias_postcode,
680
+ "bias_postcode_area": bias_postcode_area,
681
+ "bias_postcode_sector": bias_postcode_sector,
682
+ "bias_post_town": bias_post_town,
683
+ "bias_thoroughfare": bias_thoroughfare,
684
+ "bias_country": bias_country,
685
+ "postal_code": postal_code,
686
+ "postal_code_2": postal_code_2,
687
+ "postal_code_3": postal_code_3,
688
+ "city": city,
689
+ "state": state,
690
+ "state_code": state_code,
691
+ "bias_postal_code": bias_postal_code,
692
+ "bias_postal_code_2": bias_postal_code_2,
693
+ "bias_postal_code_3": bias_postal_code_3,
694
+ "bias_city": bias_city,
695
+ "bias_state": bias_state,
696
+ "bias_state_code": bias_state_code,
697
+ "is_pobox": is_pobox,
698
+ "is_business": is_business,
699
+ },
700
+ ),
701
+ ),
702
+ )
703
+
704
+ def resolve_address(self, address: str, *, tags: str | None = None) -> types.ResolveAddressResult:
705
+ """Resolve Address.
706
+
707
+ GET /autocomplete/addresses/{address}/gbr. Returns the result payload.
708
+ address: Required. ID of address suggestion provided by the API to fully resolve.
709
+ tags: Optional. A comma separated list of tags to query over.
710
+
711
+ Raises APIError, TransportError or ProtocolError on failure.
712
+ """
713
+ check_inputs(INPUTS["resolve_address"], address=address, tags=tags)
714
+ return cast(
715
+ types.ResolveAddressResult,
716
+ validate(
717
+ types.ResolveAddressResult,
718
+ self._request("GET", f"/autocomplete/addresses/{segment(address)}/gbr", query={"tags": tags}),
719
+ ),
720
+ )
721
+
722
+ @overload
723
+ def addresses(
724
+ self,
725
+ *,
726
+ query: str | None = None,
727
+ limit: int | None = None,
728
+ page: int | None = None,
729
+ filter: None = None,
730
+ lon: float | None = None,
731
+ lat: float | None = None,
732
+ postcode_outward: str | None = None,
733
+ postcode: str | None = None,
734
+ postcode_area: str | None = None,
735
+ postcode_sector: str | None = None,
736
+ post_town: str | None = None,
737
+ uprn: int | None = None,
738
+ country: str | None = None,
739
+ postcode_type: str | None = None,
740
+ su_organisation_indicator: str | None = None,
741
+ box: str | None = None,
742
+ bias_postcode_outward: str | None = None,
743
+ bias_postcode: str | None = None,
744
+ bias_postcode_area: str | None = None,
745
+ bias_postcode_sector: str | None = None,
746
+ bias_post_town: str | None = None,
747
+ bias_thoroughfare: str | None = None,
748
+ bias_country: str | None = None,
749
+ bias_lonlat: str | None = None,
750
+ tags: str | None = None,
751
+ dataset: list[types.Dataset] | None = None,
752
+ ) -> types.AddressesResult: ...
753
+
754
+ @overload
755
+ def addresses(
756
+ self,
757
+ *,
758
+ query: str | None = None,
759
+ limit: int | None = None,
760
+ page: int | None = None,
761
+ filter: str,
762
+ lon: float | None = None,
763
+ lat: float | None = None,
764
+ postcode_outward: str | None = None,
765
+ postcode: str | None = None,
766
+ postcode_area: str | None = None,
767
+ postcode_sector: str | None = None,
768
+ post_town: str | None = None,
769
+ uprn: int | None = None,
770
+ country: str | None = None,
771
+ postcode_type: str | None = None,
772
+ su_organisation_indicator: str | None = None,
773
+ box: str | None = None,
774
+ bias_postcode_outward: str | None = None,
775
+ bias_postcode: str | None = None,
776
+ bias_postcode_area: str | None = None,
777
+ bias_postcode_sector: str | None = None,
778
+ bias_post_town: str | None = None,
779
+ bias_thoroughfare: str | None = None,
780
+ bias_country: str | None = None,
781
+ bias_lonlat: str | None = None,
782
+ tags: str | None = None,
783
+ dataset: list[types.Dataset] | None = None,
784
+ ) -> types.ProjectedAddressesResult: ...
785
+
786
+ def addresses(
787
+ self,
788
+ *,
789
+ query: str | None = None,
790
+ limit: int | None = None,
791
+ page: int | None = None,
792
+ filter: str | None = None,
793
+ lon: float | None = None,
794
+ lat: float | None = None,
795
+ postcode_outward: str | None = None,
796
+ postcode: str | None = None,
797
+ postcode_area: str | None = None,
798
+ postcode_sector: str | None = None,
799
+ post_town: str | None = None,
800
+ uprn: int | None = None,
801
+ country: str | None = None,
802
+ postcode_type: str | None = None,
803
+ su_organisation_indicator: str | None = None,
804
+ box: str | None = None,
805
+ bias_postcode_outward: str | None = None,
806
+ bias_postcode: str | None = None,
807
+ bias_postcode_area: str | None = None,
808
+ bias_postcode_sector: str | None = None,
809
+ bias_post_town: str | None = None,
810
+ bias_thoroughfare: str | None = None,
811
+ bias_country: str | None = None,
812
+ bias_lonlat: str | None = None,
813
+ tags: str | None = None,
814
+ dataset: list[types.Dataset] | None = None,
815
+ ) -> types.AddressesResult | types.ProjectedAddressesResult:
816
+ """Extract Addresses.
817
+
818
+ GET /addresses. Returns the result payload.
819
+ query: Optional. Specifies the address to query.
820
+ limit: Optional. Specifies the maximum number of records to retrieve. default=10; minimum=1; maximum=100
821
+ page: Optional. 0 indexed indicator of the page of results to receive. Virtually all postcode results are returned on page 0. default=0; minimum=0; maximum=100
822
+ filter: Optional. Comma separated whitelist of address elements to return.
823
+ lon: Optional. Longitude query for reverse geocoding. minimum=-180; maximum=180
824
+ lat: Optional. Latitude query for reverse geocoding. minimum=-90; maximum=90
825
+ postcode_outward: Optional. Restrict result set to addresses with a matching outward code.
826
+ postcode: Optional. **Filter by postcode** Restrict result set to matching postcodes only. Can be combined with query to perform a postcode and building number or name search.
827
+ postcode_area: Optional. Postcode area represents the first one or two non-numeric characters of a postcode. E.g. the postcode area of `SW1A 2AA` is `SW`.
828
+ postcode_sector: Optional. Postcode sector is the outward code plus first numeric of the inward code. E.g. postcode sector of `SW1A 2AA` is `SW1A 2`
829
+ post_town: Optional. Restrict addresses to matching town, city or other locality identifier.
830
+ uprn: Optional. Does not accept comma separated terms. Only a single term is permitted.
831
+ country: Optional. Filters by country name.
832
+ postcode_type: Optional. Useful for separating organisational and residential addresses.
833
+ su_organisation_indicator: Optional. Useful for separating organisational and residential addresses.
834
+ box: Optional. Restrict search to a geospatial box determined by the 'top-left' and 'bottom-right' geolocations.
835
+ bias_postcode_outward: Optional. **Bias by Outward Code** Boosts addresses with a matching outward code. The outward code is the first half of a postcode. For instance, the outward code of `SW1A 2AA` is `SW1A`.
836
+ bias_postcode: Optional. **Bias by postcode** Boost addresses which match postcode. Can be combined with query to perform a postcode and building number or name search.
837
+ bias_postcode_area: Optional. Boosts if the first one or two non-numeric characters of a postcode match
838
+ bias_postcode_sector: Optional. Boost postcode sector matches. The postcode sector comprises the outward code plus first numeric of the inward code.
839
+ bias_post_town: Optional. Biases results to matching town, city or other locality name.
840
+ bias_thoroughfare: Optional. Bias by street or thoroughfare name.
841
+ bias_country: Optional. Possible values are England, Scotland, Wales, Northern Ireland, Jersey, Guernsey and Isle of Man.
842
+ bias_lonlat: Optional. Bias search to a geospatial circle determined by an origin and radius in metres. Max radius is `50000`. Uses the format bias_lonlat=[longitude],[latitude],[radius in metres]. Only one geospatial bias may be provided.
843
+ tags: Optional. A comma separated list of tags to query over.
844
+ dataset: Optional. Comma-separated list of datasets to search within.
845
+
846
+ Raises APIError, TransportError or ProtocolError on failure.
847
+ """
848
+ check_inputs(
849
+ INPUTS["addresses"],
850
+ query=query,
851
+ limit=limit,
852
+ page=page,
853
+ filter=filter,
854
+ lon=lon,
855
+ lat=lat,
856
+ postcode_outward=postcode_outward,
857
+ postcode=postcode,
858
+ postcode_area=postcode_area,
859
+ postcode_sector=postcode_sector,
860
+ post_town=post_town,
861
+ uprn=uprn,
862
+ country=country,
863
+ postcode_type=postcode_type,
864
+ su_organisation_indicator=su_organisation_indicator,
865
+ box=box,
866
+ bias_postcode_outward=bias_postcode_outward,
867
+ bias_postcode=bias_postcode,
868
+ bias_postcode_area=bias_postcode_area,
869
+ bias_postcode_sector=bias_postcode_sector,
870
+ bias_post_town=bias_post_town,
871
+ bias_thoroughfare=bias_thoroughfare,
872
+ bias_country=bias_country,
873
+ bias_lonlat=bias_lonlat,
874
+ tags=tags,
875
+ dataset=dataset,
876
+ )
877
+ return cast(
878
+ types.AddressesResult | types.ProjectedAddressesResult,
879
+ validate(
880
+ (types.ProjectedAddressesResult if filter is not None else types.AddressesResult),
881
+ self._request(
882
+ "GET",
883
+ "/addresses",
884
+ query={
885
+ "query": query,
886
+ "limit": limit,
887
+ "page": page,
888
+ "filter": filter,
889
+ "lon": lon,
890
+ "lat": lat,
891
+ "postcode_outward": postcode_outward,
892
+ "postcode": postcode,
893
+ "postcode_area": postcode_area,
894
+ "postcode_sector": postcode_sector,
895
+ "post_town": post_town,
896
+ "uprn": uprn,
897
+ "country": country,
898
+ "postcode_type": postcode_type,
899
+ "su_organisation_indicator": su_organisation_indicator,
900
+ "box": box,
901
+ "bias_postcode_outward": bias_postcode_outward,
902
+ "bias_postcode": bias_postcode,
903
+ "bias_postcode_area": bias_postcode_area,
904
+ "bias_postcode_sector": bias_postcode_sector,
905
+ "bias_post_town": bias_post_town,
906
+ "bias_thoroughfare": bias_thoroughfare,
907
+ "bias_country": bias_country,
908
+ "bias_lonlat": bias_lonlat,
909
+ "tags": tags,
910
+ "dataset": dataset,
911
+ },
912
+ ),
913
+ ),
914
+ )
915
+
916
+ def find_place(
917
+ self,
918
+ *,
919
+ query: str,
920
+ country_iso: str | None = None,
921
+ bias_country_iso: str | None = None,
922
+ bias_lonlat: str | None = None,
923
+ bias_ip: Literal["true"] | str | None = None,
924
+ ) -> types.FindPlaceResult:
925
+ """Find Place.
926
+
927
+ GET /places. Returns the result payload.
928
+ query: Required. Specifies the place to query. Can be shortened to `q=`
929
+ country_iso: Optional. Filter by country ISO code. Uses 3 letter country code (ISO 3166-1) standard.
930
+ bias_country_iso: Optional. **Bias by Country** Bias by country ISO code. Uses 3 letter country code (ISO 3166-1) standard. Bias by multiple countries with a comma separated list. E.g. `GBR,IRL`
931
+ bias_lonlat: Optional. Bias search to a geospatial circle determined by an origin and radius in metres. Max radius is `50000`. Uses the format bias_lonlat=[longitude],[latitude],[radius in metres]. Only one geospatial bias may be provided.
932
+ bias_ip: Optional. Biases search based on approximate geolocation of IP address. enum=['true']
933
+
934
+ Raises APIError, TransportError or ProtocolError on failure.
935
+ """
936
+ check_inputs(
937
+ INPUTS["find_place"],
938
+ query=query,
939
+ country_iso=country_iso,
940
+ bias_country_iso=bias_country_iso,
941
+ bias_lonlat=bias_lonlat,
942
+ bias_ip=bias_ip,
943
+ )
944
+ return cast(
945
+ types.FindPlaceResult,
946
+ validate(
947
+ types.FindPlaceResult,
948
+ self._request(
949
+ "GET",
950
+ "/places",
951
+ query={
952
+ "query": query,
953
+ "country_iso": country_iso,
954
+ "bias_country_iso": bias_country_iso,
955
+ "bias_lonlat": bias_lonlat,
956
+ "bias_ip": bias_ip,
957
+ },
958
+ ),
959
+ ),
960
+ )
961
+
962
+ def resolve_place(self, place: str, *, tags: str | None = None) -> types.ResolvePlaceResult:
963
+ """Resolve Place.
964
+
965
+ GET /places/{place}. Returns the result payload.
966
+ place: Required. ID of place suggestion
967
+ tags: Optional. A comma separated list of tags to query over.
968
+
969
+ Raises APIError, TransportError or ProtocolError on failure.
970
+ """
971
+ check_inputs(INPUTS["resolve_place"], place=place, tags=tags)
972
+ return cast(
973
+ types.ResolvePlaceResult,
974
+ validate(types.ResolvePlaceResult, self._request("GET", f"/places/{segment(place)}", query={"tags": tags})),
975
+ )
976
+
977
+ def list_licensees(
978
+ self,
979
+ key: str,
980
+ *,
981
+ user_token: str,
982
+ starting_after: int | None = None,
983
+ limit: int | None = None,
984
+ query: str | None = None,
985
+ ) -> types.ListLicenseesResult:
986
+ """List.
987
+
988
+ GET /keys/{key}/licensees. Returns the result payload.
989
+ key: Required. The API Key to retrieve. Begins `ak_`.
990
+ starting_after: Optional. ID of the licensee after which to list results
991
+ user_token: Required. A secret key used to manage your account and API Keys. It was previously called the user token.
992
+ limit: Optional. Specifies the maximum number of records to retrieve. default=10; minimum=1; maximum=100
993
+ query: Optional. Filter results by licensee name. Can be shortened to `q=`
994
+
995
+ Raises APIError, TransportError or ProtocolError on failure.
996
+ """
997
+ check_inputs(
998
+ INPUTS["list_licensees"],
999
+ key=key,
1000
+ user_token=user_token,
1001
+ starting_after=starting_after,
1002
+ limit=limit,
1003
+ query=query,
1004
+ )
1005
+ return cast(
1006
+ types.ListLicenseesResult,
1007
+ validate(
1008
+ types.ListLicenseesResult,
1009
+ self._request(
1010
+ "GET",
1011
+ f"/keys/{segment(key)}/licensees",
1012
+ user_token=user_token,
1013
+ query={"starting_after": starting_after, "limit": limit, "query": query},
1014
+ ),
1015
+ ),
1016
+ )
1017
+
1018
+ def create_licensee(
1019
+ self,
1020
+ key: str,
1021
+ *,
1022
+ user_token: str,
1023
+ name: str | None = None,
1024
+ address: str | None = None,
1025
+ postcode: str | None = None,
1026
+ whitelist: list[str] | None = None,
1027
+ daily: requests.CreateLicenseeDaily | None = None,
1028
+ ) -> types.CreateLicenseeResult:
1029
+ """Create.
1030
+
1031
+ POST /keys/{key}/licensees. Returns the result payload.
1032
+ key: Required. The API Key to retrieve. Begins `ak_`.
1033
+ user_token: Required. A secret key used to manage your account and API Keys. It was previously called the user token.
1034
+ name: Optional. Licensee individual or organisation name
1035
+ address: Optional. Licensee's first, second and third line address as well as post town concatenated by commas
1036
+ postcode: Optional. Licensee's postcode
1037
+ whitelist: Optional. A list of allowed URLs. An empty list disables the check.
1038
+ daily: Optional.
1039
+
1040
+ Raises APIError, TransportError or ProtocolError on failure.
1041
+ """
1042
+ check_inputs(
1043
+ INPUTS["create_licensee"],
1044
+ key=key,
1045
+ user_token=user_token,
1046
+ name=name,
1047
+ address=address,
1048
+ postcode=postcode,
1049
+ whitelist=whitelist,
1050
+ daily=daily,
1051
+ )
1052
+ return cast(
1053
+ types.CreateLicenseeResult,
1054
+ validate(
1055
+ types.CreateLicenseeResult,
1056
+ self._request(
1057
+ "POST",
1058
+ f"/keys/{segment(key)}/licensees",
1059
+ user_token=user_token,
1060
+ body=fields(
1061
+ {"name": name, "address": address, "postcode": postcode, "whitelist": whitelist, "daily": daily}
1062
+ ),
1063
+ ),
1064
+ ),
1065
+ )
1066
+
1067
+ def retrieve_licensee(self, key: str, licensee: str, *, user_token: str) -> types.RetrieveLicenseeResult:
1068
+ """Retrieve.
1069
+
1070
+ GET /keys/{key}/licensees/{licensee}. Returns the result payload.
1071
+ key: Required. The API Key to retrieve. Begins `ak_`.
1072
+ licensee: Required. Uniquely identifies a licensee.
1073
+ user_token: Required. A secret key used to manage your account and API Keys. It was previously called the user token.
1074
+
1075
+ Raises APIError, TransportError or ProtocolError on failure.
1076
+ """
1077
+ check_inputs(INPUTS["retrieve_licensee"], key=key, licensee=licensee, user_token=user_token)
1078
+ return cast(
1079
+ types.RetrieveLicenseeResult,
1080
+ validate(
1081
+ types.RetrieveLicenseeResult,
1082
+ self._request("GET", f"/keys/{segment(key)}/licensees/{segment(licensee)}", user_token=user_token),
1083
+ ),
1084
+ )
1085
+
1086
+ def delete_licensee(self, key: str, licensee: str, *, user_token: str) -> types.DeleteLicenseeResult:
1087
+ """Cancel.
1088
+
1089
+ DELETE /keys/{key}/licensees/{licensee}. Returns the result payload.
1090
+ key: Required. The API Key to retrieve. Begins `ak_`.
1091
+ licensee: Required. Uniquely identifies a licensee.
1092
+ user_token: Required. A secret key used to manage your account and API Keys. It was previously called the user token.
1093
+
1094
+ Raises APIError, TransportError or ProtocolError on failure.
1095
+ """
1096
+ check_inputs(INPUTS["delete_licensee"], key=key, licensee=licensee, user_token=user_token)
1097
+ return cast(
1098
+ types.DeleteLicenseeResult,
1099
+ validate(
1100
+ types.DeleteLicenseeResult,
1101
+ self._request("DELETE", f"/keys/{segment(key)}/licensees/{segment(licensee)}", user_token=user_token),
1102
+ ),
1103
+ )
1104
+
1105
+ def update_licensee(
1106
+ self,
1107
+ key: str,
1108
+ licensee: str,
1109
+ *,
1110
+ user_token: str,
1111
+ name: str | None = None,
1112
+ address: str | None = None,
1113
+ postcode: str | None = None,
1114
+ whitelist: list[str] | None = None,
1115
+ daily: requests.UpdateLicenseeDaily | None = None,
1116
+ ) -> types.UpdateLicenseeResult:
1117
+ """Update.
1118
+
1119
+ POST /keys/{key}/licensees/{licensee}. Returns the result payload.
1120
+ key: Required. The API Key to retrieve. Begins `ak_`.
1121
+ licensee: Required. Uniquely identifies a licensee.
1122
+ user_token: Required. A secret key used to manage your account and API Keys. It was previously called the user token.
1123
+ name: Optional. Licensee individual or organisation name
1124
+ address: Optional. Licensee's first, second and third line address as well as post town concatenated by commas
1125
+ postcode: Optional. Licensee's postcode
1126
+ whitelist: Optional. A list of allowed URLs. An empty list disables the check.
1127
+ daily: Optional.
1128
+
1129
+ Raises APIError, TransportError or ProtocolError on failure.
1130
+ """
1131
+ check_inputs(
1132
+ INPUTS["update_licensee"],
1133
+ key=key,
1134
+ licensee=licensee,
1135
+ user_token=user_token,
1136
+ name=name,
1137
+ address=address,
1138
+ postcode=postcode,
1139
+ whitelist=whitelist,
1140
+ daily=daily,
1141
+ )
1142
+ return cast(
1143
+ types.UpdateLicenseeResult,
1144
+ validate(
1145
+ types.UpdateLicenseeResult,
1146
+ self._request(
1147
+ "POST",
1148
+ f"/keys/{segment(key)}/licensees/{segment(licensee)}",
1149
+ user_token=user_token,
1150
+ body=fields(
1151
+ {"name": name, "address": address, "postcode": postcode, "whitelist": whitelist, "daily": daily}
1152
+ ),
1153
+ ),
1154
+ ),
1155
+ )
1156
+
1157
+ def regenerate_licensee_key(self, key: str, licensee: str, *, user_token: str) -> types.RegenerateLicenseeKeyResult:
1158
+ """Regenerate Key.
1159
+
1160
+ POST /keys/{key}/licensees/{licensee}/regenerate-key. Returns the result payload.
1161
+ key: Required. The API Key to retrieve. Begins `ak_`.
1162
+ licensee: Required. Uniquely identifies a licensee.
1163
+ user_token: Required. A secret key used to manage your account and API Keys. It was previously called the user token.
1164
+
1165
+ Raises APIError, TransportError or ProtocolError on failure.
1166
+ """
1167
+ check_inputs(INPUTS["regenerate_licensee_key"], key=key, licensee=licensee, user_token=user_token)
1168
+ return cast(
1169
+ types.RegenerateLicenseeKeyResult,
1170
+ validate(
1171
+ types.RegenerateLicenseeKeyResult,
1172
+ self._request(
1173
+ "POST", f"/keys/{segment(key)}/licensees/{segment(licensee)}/regenerate-key", user_token=user_token
1174
+ ),
1175
+ ),
1176
+ )
1177
+
1178
+ def list_configs(self, key: str, *, user_token: str) -> types.ListConfigsResult:
1179
+ """List.
1180
+
1181
+ GET /keys/{key}/configs. Returns the result payload.
1182
+ key: Required. The API Key to retrieve. Begins `ak_`.
1183
+ user_token: Required. A secret key used to manage your account and API Keys. It was previously called the user token.
1184
+
1185
+ Raises APIError, TransportError or ProtocolError on failure.
1186
+ """
1187
+ check_inputs(INPUTS["list_configs"], key=key, user_token=user_token)
1188
+ return cast(
1189
+ types.ListConfigsResult,
1190
+ validate(
1191
+ types.ListConfigsResult, self._request("GET", f"/keys/{segment(key)}/configs", user_token=user_token)
1192
+ ),
1193
+ )
1194
+
1195
+ def create_config(self, key: str, *, user_token: str, name: str, payload: str) -> types.CreateConfigResult:
1196
+ """Create.
1197
+
1198
+ POST /keys/{key}/configs. Returns the result payload.
1199
+ key: Required. The API Key to retrieve. Begins `ak_`.
1200
+ user_token: Required. A secret key used to manage your account and API Keys. It was previously called the user token.
1201
+ name: Required. A unique name to identify the configuration payload minLength=1; maxLength=32
1202
+ payload: Required. A serialised payload of up to `65536` characters minLength=0; maxLength=65536
1203
+
1204
+ Raises APIError, TransportError or ProtocolError on failure.
1205
+ """
1206
+ check_inputs(INPUTS["create_config"], key=key, user_token=user_token, name=name, payload=payload)
1207
+ return cast(
1208
+ types.CreateConfigResult,
1209
+ validate(
1210
+ types.CreateConfigResult,
1211
+ self._request(
1212
+ "POST",
1213
+ f"/keys/{segment(key)}/configs",
1214
+ user_token=user_token,
1215
+ body=fields({"name": name, "payload": payload}),
1216
+ ),
1217
+ ),
1218
+ )
1219
+
1220
+ def retrieve_config(self, key: str, config: str) -> types.RetrieveConfigResult:
1221
+ """Retrieve.
1222
+
1223
+ GET /keys/{key}/configs/{config}. Returns the result payload.
1224
+ key: Required. The API Key to retrieve. Begins `ak_`.
1225
+ config: Required. User-provided configuration object name.
1226
+
1227
+ Raises APIError, TransportError or ProtocolError on failure.
1228
+ """
1229
+ check_inputs(INPUTS["retrieve_config"], key=key, config=config)
1230
+ return cast(
1231
+ types.RetrieveConfigResult,
1232
+ validate(
1233
+ types.RetrieveConfigResult, self._request("GET", f"/keys/{segment(key)}/configs/{segment(config)}")
1234
+ ),
1235
+ )
1236
+
1237
+ def delete_config(self, key: str, config: str, *, user_token: str) -> types.DeleteConfigResult:
1238
+ """Delete.
1239
+
1240
+ DELETE /keys/{key}/configs/{config}. Returns the result payload.
1241
+ key: Required. The API Key to retrieve. Begins `ak_`.
1242
+ config: Required. User-provided configuration object name.
1243
+ user_token: Required. A secret key used to manage your account and API Keys. It was previously called the user token.
1244
+
1245
+ Raises APIError, TransportError or ProtocolError on failure.
1246
+ """
1247
+ check_inputs(INPUTS["delete_config"], key=key, config=config, user_token=user_token)
1248
+ return cast(
1249
+ types.DeleteConfigResult,
1250
+ validate(
1251
+ types.DeleteConfigResult,
1252
+ self._request("DELETE", f"/keys/{segment(key)}/configs/{segment(config)}", user_token=user_token),
1253
+ ),
1254
+ )
1255
+
1256
+ def update_config(
1257
+ self, key: str, config: str, *, user_token: str, payload: str | None = None
1258
+ ) -> types.UpdateConfigResult:
1259
+ """Update.
1260
+
1261
+ POST /keys/{key}/configs/{config}. Returns the result payload.
1262
+ key: Required. The API Key to retrieve. Begins `ak_`.
1263
+ config: Required. User-provided configuration object name.
1264
+ user_token: Required. A secret key used to manage your account and API Keys. It was previously called the user token.
1265
+ payload: Optional. A serialised payload of up to `65536` characters minLength=0; maxLength=65536
1266
+
1267
+ Raises APIError, TransportError or ProtocolError on failure.
1268
+ """
1269
+ check_inputs(INPUTS["update_config"], key=key, config=config, user_token=user_token, payload=payload)
1270
+ return cast(
1271
+ types.UpdateConfigResult,
1272
+ validate(
1273
+ types.UpdateConfigResult,
1274
+ self._request(
1275
+ "POST",
1276
+ f"/keys/{segment(key)}/configs/{segment(config)}",
1277
+ user_token=user_token,
1278
+ body=fields({"payload": payload}),
1279
+ ),
1280
+ ),
1281
+ )
1282
+
1283
+ def email_validation(self, *, query: str, tags: str | None = None) -> types.EmailValidationResult:
1284
+ """Email Validation.
1285
+
1286
+ GET /emails. Returns the result payload.
1287
+ query: Required. Specifies the email address to validate
1288
+ tags: Optional. A comma separated list of tags to query over.
1289
+
1290
+ Raises APIError, TransportError or ProtocolError on failure.
1291
+ """
1292
+ check_inputs(INPUTS["email_validation"], query=query, tags=tags)
1293
+ return cast(
1294
+ types.EmailValidationResult,
1295
+ validate(
1296
+ types.EmailValidationResult, self._request("GET", "/emails", query={"query": query, "tags": tags})
1297
+ ),
1298
+ )
1299
+
1300
+ def phone_number_validation(
1301
+ self, *, query: str, current_carrier: Literal["true"] | str | None = None, tags: str | None = None
1302
+ ) -> types.PhoneNumberValidationResult:
1303
+ """Phone Number Validation.
1304
+
1305
+ GET /phone_numbers. Returns the result payload.
1306
+ query: Required. Specifies the phone number to validate. Phone number must include a country code in an acceptable format. For instance, UK phone numbers should be prefixed with `+44`, `44` or `0044`.
1307
+ current_carrier: Optional. When set to `true`, the API retrieves and populates the current network of the phone number. enum=['true']
1308
+ tags: Optional. A comma separated list of tags to query over.
1309
+
1310
+ Raises APIError, TransportError or ProtocolError on failure.
1311
+ """
1312
+ check_inputs(INPUTS["phone_number_validation"], query=query, current_carrier=current_carrier, tags=tags)
1313
+ return cast(
1314
+ types.PhoneNumberValidationResult,
1315
+ validate(
1316
+ types.PhoneNumberValidationResult,
1317
+ self._request(
1318
+ "GET", "/phone_numbers", query={"query": query, "current_carrier": current_carrier, "tags": tags}
1319
+ ),
1320
+ ),
1321
+ )