-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathopenapi.yaml
More file actions
13580 lines (12944 loc) · 436 KB
/
openapi.yaml
File metadata and controls
13580 lines (12944 loc) · 436 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
openapi: 3.0.3
info:
version: 4.11.0
license:
name: AGPLv3
url: https://opensource.org/licenses/AGPL-3.0
title: API Reference
termsOfService: https://terms.ideal-postcodes.co.uk
description: |
## Getting Started
All API methods are either a `GET`, `POST` or `OPTIONS` request.
The API communicates over both HTTPS and plain HTTP using IPv4 and IPv6.
We recommend using HTTPS only although HTTP is available.
We use appropriate HTTP status codes where possible to indicate the request status.
## OpenAPI Spec
Our OpenAPI specification is available at:
- [Github Repository](https://github.com/ideal-postcodes/openapi)
- [API Reference](https://openapi.ideal-postcodes.co.uk)
- [OpenAPI v3 JSON File](https://openapi.ideal-postcodes.co.uk/openapi.json)
- [OpenAPI v3 YAML File](https://openapi.ideal-postcodes.co.uk/openapi.yaml)
- [NPM Package](https://www.npmjs.com/package/@ideal-postcodes/openapi)
## Rate Limiting
Each IP address is rate limited at 30 requests per second. Tripping the rate limit will result in a 503 response.
The autocomplete API also has an additional rate limit.
If you expect to breach the limit please contact us and we can move you to an endpoint with a higher limit.
## Authentication
Most requests require an **API key** for authentication. Authenticate by passing an `api_key` as part of the query string. For example:
```
api.ideal-postcodes.co.uk/v1/autocomplete/addresses?api_key=iddqd&q=parkside
```
Alternatively, authentication can be transmitted via the `Authorization` header using the following scheme:
```
Authorization: api_key="iddqd" [other_key="foo"]
```
## Versioning
This API is versioned with a simple prefix in the URL. The current version is `/v1/`. We will maintain backwards-compatibility by releasing breaking changes under a new version.
Please note that the following changes are backwards-compatible:
- Adding new properties to existing API responses
- Adding new API endpoints
- Adding new optional request parameters to existing API endpoints
- Changing the order of properties in existing API responses
- Changing the autocomplete address suggestion format
## Error Handling
A successful lookup is accompanied with a HTTP status code of 200 and a response code of 2000 (found in the body).
An error has occurred if the HTTP status code is not 200. Errors can range from a benign 404 (resource not found) to more urgent errors (your API Key ran out of credit, failed authentication, etc).
## Testing
Each new account comes with a free test balance. Contact us if you need more for testing and integration.
## Metadata
Requests that affect your balance may be annotated with arbitrary metadata. This data is stored along with your lookup history and can be queried at a later date via the API or the dashboard. We call the ability to label your requests [tagging](https://docs.ideal-postcodes.co.uk/docs/guides/tags).
## Response Codes
The API returns two indicators to help you to determine the status of each HTTP request.
The first is the **HTTP Status**, which is found in the status-line of all HTTP requests. The API will return status codes that adhere to HTTP /1.1 Specifications wherever possible.
`2XX` status codes indicates success while `4XX` and `5XX` indicate client and server errors respectively.
The second is the **API response code**, which can be found in the `code` property of the response body. This code will provide a more specific reason if a failure has occurred and can point you in the right direction when debugging.
contact:
email: support@ideal-postcodes.co.uk
name: Support
url: https://ideal-postcodes.co.uk/support
servers:
- url: https://api.ideal-postcodes.co.uk/v1
description: API Server
variables: {}
tags:
- name: Address Search
description: Global address autocomplete, for search-as-you-type
- name: Place Search
description: Global places search to identify geographical names and places
- name: UK
description: UK Address and Postcode Search
- name: Keys
description: Monitor and manage API Keys
- name: Licensees
description: |
The Licensee resource represents an alternate legal End User of our data who may not be the same entity as the owners of the account.
The concept of Licensees underpins our sublicensing platform, which allows users to license multiple external organisations or individuals to access data under the same account.
Sublicensing is ideal for platform vendors, who provide services to multiple clients who in turn each have their own users.
- name: Configs
description: |
The Config resource allows users to assign serialised configuration data to API Keys. The payloads assigned to a Config object can later be retrieved to dynamically configure your integration.
Useful if you need to configure your integration remotely rather than editing code in situ.
- name: suggestion
x-displayName: Address Suggestion
description: |
Address Suggestions are simple, human readable representations of an address. This format is sufficient tfor a user to determine an address match in an address autocomplete interface. A second request must be made to the API to gather fully validated address.
See our Address Search APIs for more information on address autocompletion.
<SchemaDefinition schemaRef="#/components/schemas/AddressSuggestion" />
- name: usps_address
x-displayName: US Address
description: |
Standard US Address format as reported by USPS.
<SchemaDefinition schemaRef="#/components/schemas/UspsAddress" />
- name: uk_address
x-displayName: UK Address
description: |
Standard UK Address format as reported by Royal Mail's Postcode Address File (PAF). PAF is the most complete and up-to-date address database in the UK.
<SchemaDefinition schemaRef="#/components/schemas/PafAddress" />
- name: ecaf_address
x-displayName: IE Address
description: |
Standard Republic of Ireland Address format as reported by the Eircode ECAF file.
<SchemaDefinition schemaRef="#/components/schemas/EcafAddress" />
- name: ecad_address
x-displayName: IE Address (ECAD)
description: |
ECAF file including additional data for each address.
<SchemaDefinition schemaRef="#/components/schemas/EcadAddress" />
- name: ab_address
x-displayName: AddressBase Core
description: |
AddressBase Core Address. An alternative to UK PAF dataset from Ordnance Survey.
Please contact us to have this enabled on your account.
<SchemaDefinition schemaRef="#/components/schemas/AddressBaseCore" />
- name: geonames_place
x-displayName: GeoNames Place
description: |
GeoNames place record
<SchemaDefinition schemaRef="#/components/schemas/GeonamesPlace" />
externalDocs:
description: More on our APIs, libraries with guides and examples
url: https://docs.ideal-postcodes.co.uk
paths:
/postcodes/{postcode}:
get:
tags:
- UK
summary: Lookup Postcode
operationId: Postcodes
description: |
Returns the complete list of addresses for a postcode. Postcode searches are space and case insensitive.
The Postcode Lookup API provides a JSON interface to search UK addresses from a postcode. It can be used to power Postcode Lookup driven address searches, like [Postcode Lookup](/postcode-lookup).
## Postcode Not Found
Lookup balance is unaffected by invalid postcodes. The API returns a `404` response with response body:
```json
{
"code": 4040,
"message": "Postcode not found",
"suggestions": ["SW1A 0AA"]
}
```
### Suggestions
If a postcode cannot be found, the API will provide up to 5 closest matching postcodes. Common errors will be corrected first (e.g. mixing up `O` and `0` or `I` and `1`).
If the suggestion list is small (fewer than 3), there is a high probability the correct postcode is there. You may notify the user or immediately trigger new searches.
The suggestion list will be empty if the postcode has deviated too far from a valid postcode format.
## Multiple Residence
A small number of postcodes will return more than 100 premises. These may require pagination. Use `page` to paginate the result set.
parameters:
- name: postcode
in: path
description: Postcode to retrieve
required: true
style: simple
explode: false
example: SW1A 2AA
schema:
type: string
- $ref: '#/components/parameters/ApiKeyParam'
- $ref: '#/components/parameters/FilterParam'
- $ref: '#/components/parameters/PageParam'
- $ref: '#/components/parameters/TagsParam'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/PostcodeResponse'
examples:
Postcode Found:
value:
result:
- postcode: SW1A 2AA
postcode_inward: 2AA
postcode_outward: SW1A
post_town: London
dependant_locality: ''
double_dependant_locality: ''
thoroughfare: Downing Street
dependant_thoroughfare: ''
building_number: '10'
building_name: ''
sub_building_name: ''
po_box: ''
department_name: ''
organisation_name: Prime Minister & First Lord Of The Treasury
udprn: 23747771
postcode_type: L
su_organisation_indicator: ''
delivery_point_suffix: 1A
line_1: Prime Minister & First Lord Of The Treasury
line_2: 10 Downing Street
line_3: ''
premise: '10'
longitude: -0.12767
latitude: 51.503541
eastings: 530047
northings: 179951
country: England
traditional_county: Greater London
administrative_county: ''
postal_county: London
county: London
district: Westminster
ward: St. James's
uprn: '100023336956'
id: paf_23747771
country_iso: GBR
country_iso_2: GB
county_code: ''
language: en
umprn: ''
dataset: paf
code: 2000
message: Success
limit: 100
page: 0
total: 1
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
'404':
description: Postcode Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/PostcodeNotFoundResponse'
x-codeSamples:
- lang: http
label: URL
source: |
https://api.ideal-postcodes.co.uk/v1/postcodes/SW1A2AA?api_key=iddqd
- lang: cURL
label: CLI
source: |
curl -G -k \
--url 'https://api.ideal-postcodes.co.uk/v1/postcodes/SW1A2AA' \
--d "api_key=iddqd"
/udprn/{udprn}:
get:
tags:
- UK
summary: Retrieve by UDPRN
operationId: UDPRN
description: |
Returns an address as identified by its Unique Delivery Point Reference Number (UDPRN).
You may find it useful to store UDPRN information as it can be used to retrieve the most recent information for an address. It can also be used to test for a deleted address.
UDPRNs are an eight digit unique numeric code (e.g. `25962203`) for any premise on the Postcode Address File. It's essentially a unique identifier for every address in the UK that Royal Mail has in its database.
## Testing
To test your implementation of our API we have a range of test UDPRNs that yield both successful and unsuccessful responses to your request.
They are the following:
- `0` Returns a successful UDPRN lookup response
`2000`
- `-1` Returns "UDPRN not found", error `4044`
- `-2` Returns "no lookups remaining", error `4020`
- `-3` Returns "daily (or individual) lookup limit breached",
error `4021`
Test request undergo the usual authentication and restriction rules. This is to help surface any issues that occur during implementation and does not cost you a lookup.
parameters:
- name: udprn
in: path
description: UDPRN to be retrieved
required: true
style: simple
explode: false
schema:
type: string
- $ref: '#/components/parameters/ApiKeyParam'
- $ref: '#/components/parameters/FilterParam'
responses:
'200':
description: Success
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/UDPRNResponse'
examples:
Valid UDPRN:
value:
result:
postcode: SW1A 2AA
postcode_inward: 2AA
postcode_outward: SW1A
post_town: London
dependant_locality: ''
double_dependant_locality: ''
thoroughfare: Downing Street
dependant_thoroughfare: ''
building_number: '10'
building_name: ''
sub_building_name: ''
po_box: ''
department_name: ''
organisation_name: Prime Minister & First Lord Of The Treasury
udprn: 23747771
postcode_type: L
su_organisation_indicator: ''
delivery_point_suffix: 1A
line_1: Prime Minister & First Lord Of The Treasury
line_2: 10 Downing Street
line_3: ''
premise: '10'
longitude: -0.12767
latitude: 51.503541
eastings: 530047
northings: 179951
country: England
traditional_county: Greater London
administrative_county: ''
postal_county: London
county: London
district: Westminster
ward: St. James's
uprn: '100023336956'
id: paf_23747771
country_iso: GBR
country_iso_2: GB
county_code: ''
language: en
umprn: ''
dataset: paf
code: 2000
message: Success
'404':
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-codeSamples:
- lang: http
label: URL
source: |
https://api.ideal-postcodes.co.uk/v1/udprn/0?api_key=iddqd
- lang: cURL
label: CLI
source: |
curl -k -G https://api.ideal-postcodes.co.uk/v1/udprn/0 \
-d "api_key=iddqd"
/umprn/{umprn}:
get:
tags:
- UK
summary: Retrieve by UMPRN
operationId: UMPRN
description: |
Returns a multiple occupancy address identified via its UMPRN (Multiple Residence Unique ID).
UMPRNs are a unique numeric code for any Multiple Residence household on the optional Multiple Residence dataset.
## Testing
To test your implementation of our API we have a range of test UMPRNs that yield both successful and unsuccessful responses to your request. They are the following
- `0` Returns a successful UMPRN lookup response `2000`
- `-1` Returns "UMPRN not found", error `4044`
- `-2` Returns "no lookups remaining", error `4020`
- `-3` Returns "daily (or individual) lookup limit breached", error `4021`
Test request undergo the usual authentication and restriction rules. This is to help surface any issues that occur during implementation and does not cost you a lookup.
### Pricing
Per lookup charges apply. Empty responses are not charged.
parameters:
- name: umprn
in: path
description: UMPRN to be retrieved
required: true
style: simple
explode: false
schema:
type: string
- $ref: '#/components/parameters/ApiKeyParam'
- $ref: '#/components/parameters/FilterParam'
responses:
'200':
description: Success
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/UMPRNResponse'
examples:
Valid UMPRN:
value:
result:
postcode: CV4 7AL
postcode_inward: 7AL
postcode_outward: CV4
post_town: Coventry
dependant_locality: ''
double_dependant_locality: ''
thoroughfare: Gibbet Hill Road
dependant_thoroughfare: ''
building_number: ''
building_name: Block 1 Arthur Vick
sub_building_name: Room 249a
po_box: ''
department_name: ''
organisation_name: ''
udprn: 5770157
postcode_type: S
su_organisation_indicator: ''
delivery_point_suffix: 1A
line_1: Room 249a, Block 1 Arthur Vick
line_2: Gibbet Hill Road
line_3: ''
premise: Room 249a, Block 1 Arthur Vick
longitude: -1.5648072
latitude: 52.3858227
eastings: 429716
northings: 276509
country: England
traditional_county: Warwickshire
administrative_county: ''
postal_county: West Midlands
county: West Midlands
district: Coventry
ward: Wainbody
uprn: '200001572050'
id: mr_50906058
country_iso: GBR
country_iso_2: GB
county_code: ''
language: en
umprn: 50906058
dataset: mr
code: 2000
message: Success
'404':
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-codeSamples:
- lang: http
label: URL
source: |
https://api.ideal-postcodes.co.uk/v1/umprn/0?api_key=iddqdmr
- lang: cURL
label: CLI
source: |
curl -k -G https://api.ideal-postcodes.co.uk/v1/umprn/0 \
-d "api_key=iddqdmr"
/keys/{key}:
get:
tags:
- Keys
summary: Availability
operationId: KeyAvailability
description: |
Returns public information on your API Key.
This endpoint can be used for the following:
- Determine if the key is currently usable via the `available` property
- Determine available contexts for an API Key
- Identify the currently likely context of a user given their location
You may pass both API Keys (beginning `ak_`) and Sub-licensed Keys (beginning `sl_`).
parameters:
- $ref: '#/components/parameters/ApiKeyPathParam'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKeyResponse'
'404':
description: Invalid Key
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/keys/{key}/details:
get:
tags:
- Keys
summary: Details
operationId: KeyDetails
description: |
Returns private data on the key including remaining lookups, available datasets and usage limits.
parameters:
- $ref: '#/components/parameters/ApiKeyPathParam'
- $ref: '#/components/parameters/UserTokenParam'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKeyDetailsResponse'
'401':
description: Unauthorised
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
deprecated: false
put:
tags:
- Keys
summary: Update Details
description: Update API Key Details
operationId: UpdateKeyDetails
parameters:
- $ref: '#/components/parameters/ApiKeyPathParam'
- $ref: '#/components/parameters/UserTokenParam'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKeyDetailsEditable'
required: true
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKeyDetailsResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
'401':
description: Unauthorised
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/keys/{key}/usage:
get:
tags:
- Keys
summary: Usage Stats
operationId: KeyUsage
description: |
Reports the number of lookups consumed on a key for a range of days.
A maximum interval of 90 days can be provided for analysis. If no start or end date is provided, the last 21 days will be used as the default interval.
If no `start` time is provided, the start time will be set to 21 days prior to the current time.
If no `end` time is provided, the current time will be used.
Append `tags` to scope the number of lookups to those with matching tag values. E.g. `tags=foo,bar` will only count transactions that match `foo` and `bar`.
parameters:
- $ref: '#/components/parameters/ApiKeyPathParam'
- $ref: '#/components/parameters/UserTokenParam'
- $ref: '#/components/parameters/StartParam'
- $ref: '#/components/parameters/EndParam'
- $ref: '#/components/parameters/TagsParam'
- $ref: '#/components/parameters/LicenseeParam'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKeyUsageResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
x-codeSamples:
- lang: http
label: URL
source: |
https://api.ideal-postcodes.co.uk/v1/keys/iddqd/usage?user_token=my_secret_token
- lang: cURL
label: CLI
source: |
curl -k -G https://api.ideal-postcodes.co.uk/v1/keys/iddqd/usage \
-d "user_token=my_secret_token"
/keys/{key}/lookups:
get:
tags:
- Keys
summary: Logs (CSV)
operationId: KeyLogs
description: |
Reports lookup information on a key for paid lookups.
This method requires a `user_token`, which can be found on your [accounts page](https://ideal-postcodes.co.uk/account).
A maximum interval of 90 days can be provided for analysis. If no start or end date is provided, the last 21 days will be used as the default interval.
## Download Usage History (CSV)
`GET /keys/:key/lookups`
Returns a CSV download of lookups performed and associated information.
Note that the Content-Type returned will be CSV (text/csv). For a non 200 response, the `Content-Type` will revert to JSON with the error code and message embedded.
## Data Redaction
Personally Identifiable Data (PII) caught in this your usage log (including IP, search term and URL data) will be redacted on a weekly basis.
By default, PII will be redacted if it is older than 21 days. This timeframe can be configured from your dashboard.
You may prevent PII collection altogether by setting the interval to `0` days.
parameters:
- $ref: '#/components/parameters/ApiKeyPathParam'
- $ref: '#/components/parameters/UserTokenParam'
- $ref: '#/components/parameters/StartParam'
- $ref: '#/components/parameters/EndParam'
- $ref: '#/components/parameters/LicenseeParam'
responses:
'200':
description: Success
content:
text/csv:
example: |
2015-02-21T16:05:22.991Z,82.85.128.18,SW12AA,https://www.example.com/,Postcode Lookup,
2015-02-21T16:05:38.298Z,82.85.128.18,10 Downing Street London,https://www.example.com/,Address Lookup,CRM
2015-02-21T16:06:49.227Z,82.85.128.18,OX44PP,https://www.example.com/,Postcode Lookup,"Website,Live"
2015-02-21T16:07:02.706Z,82.85.128.18,PL9 9HE,https://www.example.com/,Postcode Lookup,
schema:
type: string
description: Success
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
x-codeSamples:
- lang: http
label: URL
source: |
https://api.ideal-postcodes.co.uk/v1/keys/iddqd/lookups?user_token=my_secret_token
- lang: cURL
label: CLI
source: |
curl -k -G https://api.ideal-postcodes.co.uk/v1/keys/iddqd/lookups \
-d "user_token=my_secret_token"
/cleanse/addresses:
post:
tags:
- UK
summary: Cleanse Address
description: |
The address cleanse API attempts to return the closest matching address for any given address inputs. We also return a number of Match Level indicators that describe the degree to which the suggested address matches the input address. The more impaired the input address, the harder it is to cleanse.
## Confidence Score
The confidence score is a number ranging between 0 and 1. Where 1 implies a full match and 0 implies no major elements completely match. Each incorrect, missing or misspelled element will subtract from the overall confidence score.
### Deciding on an Acceptable Confidence Score Threshold
Different address cleanse projects can have radically different inputs. However, within each project, the inputs tend to repeat the same errors. For instance, some input datasets may be exclusively inputted manually and be prone to typos. Others may have a persistently missing datapoint such as organisation name or postcode. For this reason, it is important to understand that there is no absolute Confidence Score threshold. Instead, the acceptable confidence score must be determined on a project by project basis based on systematic errors present in the data and business goals.
When determining an acceptable Confidence Score threshold you should load a subset of the dataset into a spreadsheet application like Excel and sort on the score. Scrolling from top-to-bottom you will be able to observe matches from best to worst. As you start to hit the lower quality searches, you will be able to roughly determine:
- Which confidence scores indicate ambiguous matches (i.e. up to building level only)
- Which confidence scores indicate a poor or no match (i.e. the nearest matching address is too far from the input address)
Depending on your business goals, you can also use the Match Levels to determine an acceptable match. For instance, do you need to match up to the thoroughfare or building name only? Are accurate organisation names an important feature?
operationId: AddressCleanse
parameters:
- $ref: '#/components/parameters/ApiKeyParam'
- $ref: '#/components/parameters/TagsParam'
- name: context
in: query
schema:
type: string
description: |
Identify the country of the address to cleanse. Defaults to UK (GBR)
example: usa
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- query
properties:
query:
type: string
description: |
Freeform address input to cleanse
example: 10 Downing Street, London, SW2A 2BN
postcode:
type: string
description: |
Optionally specify postal code for the address.
example: SW1A 2BN
post_town:
type: string
description: |
Optionally specify the city or town of the address.
For UK verifications, this should be the "post town" of the address.
For USA verifications, this should be the city of the address.
example: London
county:
type: string
description: |
Optionally specify the county or state of the address.
For UK verifications, we recommend omitting this field as county data is unreliable.
For USA verifications, this should be the state of the address.
example: Kent
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/CleanseResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
'429':
description: Rate Limited
content:
application/json:
schema:
$ref: '#/components/schemas/RateLimitedResponse'
x-codeSamples:
- lang: cURL
label: CLI
source: |
curl -k -G 'https://api.ideal-postcodes.co.uk/v1/cleanse/addresses' \
-H 'Authorization: api_key="ak_test"'
-H 'Content-Type: application/json'
-d '{"query": "10 downing street sw1a"}'
/verify/addresses:
post:
tags:
- US
summary: Verify Address
description: |
The address verify API validates, corrects, and standardizes individual addresses based on USPS's Coding Accuracy Support System (CASS).
The address verify API accepts the 3 combination of inputs:
- Free-form address submitted as a single string in `query`
- Example: "123 Main St, Springfield, CO 81073-1119"
- Only free-form and zip code address components submitted as separate parameters:
- `query` for the first address line
- `zip_code` for the ZIP code
- Example:
- `query`: "123 Main St, Springfield CO"
- `zip_code`: "81073-1119"
- Only free-form, city and state address components submitted as separate parameters:
- `query` for the first address line
- `city` for the city
- `state` for the state
- Example:
- `query`: "123 Main St"
- `city`: "Springfield"
- `state`: "CO"
operationId: AddressVerify
parameters:
- $ref: '#/components/parameters/ApiKeyParam'
- $ref: '#/components/parameters/TagsParam'
- name: context
in: query
schema:
type: string
description: |
Identify the country of the address to verify. Defaults to United States (USA)
example: usa
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- query
properties:
query:
type: string
description: |
Address input to verify.
If submitting a freeform address verification query, enter the full address. E.g. `query=123 Main St, Springfield, CO, 81073`
Otherwise, query can be accompanied with the following address components:
- `zip_code`
- `city` and `state`
If zip_code or `city` and `state` or supplied, please omit this information from query by using it purely for the first address line. E.g. `query=123 Main St`
example: 123 Main St, Springfield, CO 81073
zip_code:
type: string
description: |
Specify the zip code of an address. The following formats are accepted: `81073-1119`, `810731119`, `81073`.
example: 81073-1119
city:
type: string
description: |
City of an address. For the US, this should be the city name.
example: Springfield
state:
type: string
description: |
State of an address. For the US, this should be in the 2 letter state abbreviation format.
example: CO
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/VerifyResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
'429':
description: Rate Limited
content:
application/json:
schema:
$ref: '#/components/schemas/RateLimitedResponse'
x-codeSamples:
- lang: cURL
label: CLI
source: |
curl -k -G 'https://api.ideal-postcodes.co.uk/v1/verify/addresses' \
-H 'Authorization: api_key="ak_test"'
-H 'Content-Type: application/json'
-d '{"query": "123 Main St, Springfield, IL 62701" }'
/autocomplete/addresses:
get:
tags:
- Address Search
summary: Find Address
description: |
The Address Autocomplete API delivers address suggestions in order of relevance based on a provided query. It aids real-time address autofill implementations.
Consider using our Address Autocomplete JavaScript libraries to add address lookup to a form in moments rather than interacting with this API directly.
## API Usage
Implementing our Address Autocomplete API involves:
1. Fetch address suggestions with `/autocomplete/addresses`
2. Acquire the complete address using the ID from the suggestion
Step 2 will decrement your lookup balance.
Note that step 1 is not a free standalone resource. Integrations that consistently make autocomplete requests without a paid Step 2 request will be rate limited and then suspended.
## Query Filters
Refine results by appending filters to your querystring, e.g., `postcode=sw1a2aa` for postcode `SW1A 2AA`. Invalid filters return an empty set without affecting your lookup count.
To apply multiple filter terms, use a comma-separated list, e.g., `postcode_outward=e1,e2,e3` combines result sets for E1, E2, and E3. Unless otherwise specified, all filters support multiple terms.
Combine filters by `AND` logic, for instance, `su_organisation_indicator=Y&postcode_area=n`. The maximum allowed filter terms is **10**.
## Address Bias
Preface bias searches with `bias_` to boost certain address results. Unlike filters, biasing allows unmatched addresses to appear with lower priority.
For example, use `bias_postcode_area=SW,SE` to favor addresses in the `SW` and `SE` postcode areas. Invalid bias terms have no effect.
Multiple bias terms are allowed unless stated otherwise, with a combined maximum of **5**.
## Suggestion Format
The suggestion format is subject to change. We recommend using the suggestion as-is to prevent potential integration issues.
## Rate Limiting and Cost
The rate limit for the Autocomplete API is 3000 requests per 5 minutes. HTTP Headers inform about the current rate limit.
Autocomplete API usage does not impact your balance, but resolving a suggestion to a full address requires a paid request. Autocomplete requests without subsequent paid requests may result in rate limitation or suspension.
operationId: FindAddress
parameters:
- $ref: '#/components/parameters/ApiKeyParam'
- name: query
description: |
**Address Query**
The partial address string entered by the user to autocomplete.
example: 10 downing street lo
explode: false
in: query
schema:
type: string
maxLength: 150
style: form
- $ref: '#/components/parameters/ContextParam'
- $ref: '#/components/parameters/LimitParam'
- $ref: '#/components/parameters/BiasLonLatParam'
- $ref: '#/components/parameters/BiasIpParam'
- $ref: '#/components/parameters/BoxParam'
- $ref: '#/components/parameters/PostcodeOutwardParam'
- $ref: '#/components/parameters/PostcodeParam'
- $ref: '#/components/parameters/PostcodeAreaParam'
- $ref: '#/components/parameters/PostcodeSectorParam'
- $ref: '#/components/parameters/PostTownParam'
- $ref: '#/components/parameters/UPRNParam'