API Methods

The Ideal Postcodes Connector uses API methods to retrieve address data. The methods are detailed below.

Returns the complete list of addresses for a postcode.

Parameters:

postcode (required)	string (Postcode) `[ 6 .. 8 ] characters` Example: `SW1A 2AA` Postcode to retrieve
api_key (required)	string (API Key) Example: `api_key=ak_hk71kco54zGSGvF9eXXrvvnMOLLNh` Your Ideal Postcodes API Key. Typically beings `ak_`. Available from your dashboard
filter	string (Filter) Example: `filter=line_1,line_2,line_3` Comma separated whitelist of address elements to return. E.g. f`ilter=line_1,line_2,line_3` returns only `line_1`, `line_2` and `line_3` address elements in your response
page	integer <int32> (Page) `>= 0` Default: `0` Example: `page=0` 0 indexed indicator of the page of results to receive. Virtually all postcode results are returned on page 0.

Call Example

Request:

Copy

{
    "ApiInfo": {
        "Token": "{{access_token}}"
    },
    "Request": {
        "ActionName": "FTOS_EXTD_POST_AddressesSearch", 
        "Data": "{ \"query\" : { postcode: \"SW1A2AA\" }   }"
    }
}

Response:

Copy

{
    "UIResult": {
        "NavigateToEntityPage": false,
        "NavigateToEntityPageOnEdit": false,
        "NavigateToEntityFormName": null,
        "NavigateToEntityName": null,
        "NavigateToEntityId": null,
        "NavigateToEntityInsertDefaults": null,
        "NavigateToUrl": null,
        "DownloadFile": null,
        "ReloadPage": false,
        "Message": null,
        "IsSuccess": false,
        "Data": "{\"response\":{\"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,\"umprn\":\"\",\"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\"}],\"code\":2000,\"message\":\"Success\",\"total\":1,\"page\":0,\"limit\":100},\"pcSearchLookupId\":\"5af051d6-d1ed-4eca-acd6-fe34b9f9f6be\",\"status\":true}",
        "NavigateToPageNo": null
    },
    "Message": null,
    "IsSuccess": true,
    "ClientScript": null,
    "Serialized": null,
    "ErrorCode": 0
}

Address Search

This method queries and retrieves addresses.

Parameters:

api_key (required)	string (API Key) Example: `api_key=ak_hk71kco54zGSGvF9eXXrvvnMOLLNh` Your Ideal Postcodes API Key. Typically beings ak_. Available from your dashboard
query	string Specifies the address you wish to query. Query can be shortened to q=
limit	integer <int32> (Limit) `[ 1 .. 100 ]` Default: `10` Example: `limit=5` Specifies the maximum number of suggestions to retrieve. By default the limit is 10, unless a postcode is queried (then all addresses at that postcode will be returned). Limit can be shortened to `l=`
page	integer <int32> (Page) `>= 0` Default: `0` Example: `page=0` 0 indexed indicator of the page of results to receive. Virtually all postcode results are returned on page 0. A small number of Multiple Residence postcodes may need pagination (i.e. have more than 100 premises).
filter	string (Filter) Example: `filter=line_1,line_2,line_3` Comma separated whitelist of address elements to return. E.g. `filter=line_1,line_2,line_3` returns only `line_1, line_2 and line_3` address elements in your response
postcode_outward	string (Postcode Outward) Example: `postcode_outward=1AA` Filter by outward code.
postcode	string (Postcode) Example: postcode=SW1A 2AA Filter by postcode. Can be combined with query to perform a postcode + building number/name search.
postcode_area	string (Postcode Area) Example: `postcode_area=SW` Filter by postcode. Can be combined with query to perform a postcode + building number/name search.
postcode_sector	string (Postcode Sector) Example: `postcode_sector=SW1A 2` Filter by postcode sector, the outward code plus first numeric of the inward code.
post_town	string (Post Town) Example: `post_town=London` Filter by town.
uprn	integer (UPRN) Example: `uprn=100023336956` Filters by UPRN. Does not accept comma separated terms. Only a single term is permitted
country	string (Country) Example: `country=England` Filter by country. Possible values are England, Scotland, Wales, Northern Ireland, Jersey, Guernsey and Isle of Man.
postcode_type	string (Country) Example: `postcode_type=L` Filter by Postcode Type. Useful for separating organisational and residential addresses
su_organisation_indicator	string (SU Organisation Indicator) Example: `su_organisation_indicator=Y` Filter by Organisation Indicator. Useful for separating organisational and residential addresses
box	string (Box) Example: `box=2.095,57.15,-2.096,57.14` Restrict search to a geospatial box determined by the "top-left" and "bottom-right" gelocations. Only one geospatial box can be provided.
bias_postcode_outward	string (Bias Postcode Outward) Bias by outward code
bias_postcode	string (Bias Postcode) Example: `bias_postcode=/addresses?postcode=SW1A2AA&q=10` Bias by postcode. Can be combined with query to perform a postcode + building number/name search.
bias_postcode_area	string (Bias Postcode Area) Example: `bias_postcode_area=The postcode area of SW1A 2AA and N1 6RT are SW and N respectively` Bias by postcode area, the first one or two non-numeric characters of a postcode.
bias_postcode_sector	string (Bias Postcode Sector) Example: `bias_postcode_sector=SW1A 2AA is SW1A 2` Bias by postcode sector, the outward code plus first numeric of the inward code.
bias_post_town	string (Bias Post Town) Bias by town.
bias_thoroughfare	string (Bias Thoroughfare) Bias by street name.
bias_country	string (Bias County) Bias by country. Possible values are England, Scotland, Wales, Northern Ireland, Jersey, Guernsey and Isle of Man.
bias_lonlat	string (Bias Lon/Lat) Example: `bias_lonlat=-2.095,57.15,100` Bias search to a geospatial circle determined by an origin and radius in meters. Max radius is `50000`. Uses the format bias_lonlat=[longitude],[latitude],[radius in meters] Only one geospatial bias may be provided

Call Example

Request:

Copy

{
    "ApiInfo": {
        "Token": "{{access_token}}"
    },
    "Request": {
        "ActionName": "FTOS_EXTD_POST_AddressesSearch", 
        "Data": "{ \"query\" : {   address: \"100 downing street london\" , filters:{limit: 1}  }   }"
    }
}

Respose:

Copy

{
    "UIResult": {
        "NavigateToEntityPage": false,
        "NavigateToEntityPageOnEdit": false,
        "NavigateToEntityFormName": null,
        "NavigateToEntityName": null,
        "NavigateToEntityId": null,
        "NavigateToEntityInsertDefaults": null,
        "NavigateToUrl": null,
        "DownloadFile": null,
        "ReloadPage": false,
        "Message": null,
        "IsSuccess": false,
        "Data": "{\"response\":{\"result\":{\"total\":10000,\"limit\":1,\"page\":0,\"hits\":[{\"postcode\":\"DE55 2HF\",\"post_town\":\"ALFRETON\",\"dependant_locality\":\"South Normanton\",\"double_dependant_locality\":\"\",\"thoroughfare\":\"Downing Street\",\"dependant_thoroughfare\":\"\",\"building_number\":\"100\",\"building_name\":\"\",\"sub_building_name\":\"\",\"po_box\":\"\",\"department_name\":\"\",\"organisation_name\":\"\",\"udprn\":6748763,\"umprn\":\"\",\"postcode_type\":\"S\",\"su_organisation_indicator\":\"\",\"delivery_point_suffix\":\"1A\",\"postcode_inward\":\"2HF\",\"postcode_outward\":\"DE55\",\"line_1\":\"100 Downing Street\",\"line_2\":\"South Normanton\",\"line_3\":\"\",\"premise\":\"100\",\"longitude\":-1.3396786999999999,\"latitude\":53.1050242,\"eastings\":444305,\"northings\":356627,\"country\":\"England\",\"traditional_county\":\"Derbyshire\",\"administrative_county\":\"Derbyshire\",\"postal_county\":\"Derbyshire\",\"county\":\"Derbyshire\",\"district\":\"Bolsover\",\"ward\":\"South Normanton West\",\"uprn\":\"100030048392\"}]},\"code\":2000,\"message\":\"Success\"},\"pcSearchLookupId\":\"19818973-b854-4081-a4d3-764eea6d5a14\",\"status\":true}",
        "NavigateToPageNo": null
    },
    "Message": null,
    "IsSuccess": true,
    "ClientScript": null,
    "Serialized": null,
    "ErrorCode": 0
}

UDPRN Search

Retrieves a UK address based on its Unique Delivery Point Reference Number (UDPRN).

Parameters:

udprn (required)

string

UDPRN to be retrieved

api_key (required)

string (API Key)Example: {{api_key=ak_hk71kco54zGSGvF9eXXrvvnMOLLNh}}Your Ideal Postcodes API Key. Typically beings {{ak_}}.Available from your dashboard

filter

string (Filter)Example: {{filter=line_1,line_2,line_3}}Comma separated whitelist of address elements to return.E.g. {{filter=line_1,line_2,line_3}} returns only {{line_1}}, {{line_2}} and {{line_3}} address elements in your response

Call Example

Request:

Copy

{
    "ApiInfo": {
        "Token": "{{access_token}}"
    },
    "Request": {
        "ActionName": "FTOS_EXTD_POST_AddressesSearch", 
        "Data": "{ \"query\" : {   udprn: \"7040203\"  }   }"
    }
}

Response:

Copy

{
    "UIResult": {
        "NavigateToEntityPage": false,
        "NavigateToEntityPageOnEdit": false,
        "NavigateToEntityFormName": null,
        "NavigateToEntityName": null,
        "NavigateToEntityId": null,
        "NavigateToEntityInsertDefaults": null,
        "NavigateToUrl": null,
        "DownloadFile": null,
        "ReloadPage": false,
        "Message": null,
        "IsSuccess": false,
        "Data": "{\"response\":{\"result\":{\"postcode\":\"DL1 2YG\",\"postcode_inward\":\"2YG\",\"postcode_outward\":\"DL1\",\"post_town\":\"DARLINGTON\",\"dependant_locality\":\"\",\"double_dependant_locality\":\"\",\"thoroughfare\":\"Downing Court\",\"dependant_thoroughfare\":\"\",\"building_number\":\"10\",\"building_name\":\"\",\"sub_building_name\":\"\",\"po_box\":\"\",\"department_name\":\"\",\"organisation_name\":\"\",\"udprn\":7040203,\"umprn\":\"\",\"postcode_type\":\"S\",\"su_organisation_indicator\":\"\",\"delivery_point_suffix\":\"1N\",\"line_1\":\"10 Downing Court\",\"line_2\":\"\",\"line_3\":\"\",\"premise\":\"10\",\"longitude\":-1.5426173,\"latitude\":54.5428546,\"eastings\":429689,\"northings\":516494,\"country\":\"England\",\"traditional_county\":\"Durham\",\"administrative_county\":\"\",\"postal_county\":\"County Durham\",\"county\":\"County Durham\",\"district\":\"Darlington\",\"ward\":\"North Road\",\"uprn\":\"100110541757\"},\"code\":2000,\"message\":\"Success\"},\"pcSearchLookupId\":\"61934243-5bf5-44d2-b6d3-a7f55e7fdb21\",\"status\":true}",
        "NavigateToPageNo": null
    },
    "Message": null,
    "IsSuccess": true,
    "ClientScript": null,
    "Serialized": null,
    "ErrorCode": 0
}

Address Autocomplete

Retrieves a list of address suggestions that match the query.

Parameters:

postcode (required)	string (Postcode) `[ 6 .. 8 ] characters` Example: `SW1A 2AA` Postcode to retrieve
api_key (required)	string (API Key) Example: `api_key=ak_hk71kco54zGSGvF9eXXrvvnMOLLNh` Your Ideal Postcodes API Key. Typically beings `ak_`. Available from your dashboard
filter	string (Filter) Example: `filter=line_1,line_2,line_3` Comma separated whitelist of address elements to return. E.g. f`ilter=line_1,line_2,line_3` returns only `line_1`, `line_2` and `line_3` address elements in your response
page	integer <int32> (Page) `>= 0` Default: `0` Example: `page=0` 0 indexed indicator of the page of results to receive. Virtually all postcode results are returned on page 0.

The response is saved in JSON format with the following structure:

xPath	Description
/result[*]/suggestion	Suggested address
/result[*]/urls/udprn	Link to address by UDPRN
/result[*]/udprn	Unique Delivery Point Reference Number
/code	Response code
/message	Response description

Call Example

Request:

Copy

{
    "ApiInfo": {
        "Token": "{{access_token}}"
    },
    "Request": {
        "ActionName": "FTOS_EXTD_POST_AddressesAutocomplete", 
        "Data": "{ \"query\" : {   address: \"10 down\"  }   }"
    }
}

Response:

Copy

{
    "UIResult": {
        "NavigateToEntityPage": false,
        "NavigateToEntityPageOnEdit": false,
        "NavigateToEntityFormName": null,
        "NavigateToEntityName": null,
        "NavigateToEntityId": null,
        "NavigateToEntityInsertDefaults": null,
        "NavigateToUrl": null,
        "DownloadFile": null,
        "ReloadPage": false,
        "Message": null,
        "IsSuccess": false,
        "Data": "{\"response\":{\"result\":{\"hits\":[{\"suggestion\":\"10 Down Avenue, Bath, BA2\",\"urls\":{\"udprn\":\"/v1/udprn/1155007\"},\"udprn\":1155007},{\"suggestion\":\"10 Down Road, Teddington, TW11\",\"urls\":{\"udprn\":\"/v1/udprn/25507639\"},\"udprn\":25507639},{\"suggestion\":\"10 Down Close, Weymouth, DT4\",\"urls\":{\"udprn\":\"/v1/udprn/7573952\"},\"udprn\":7573952},{\"suggestion\":\"10 Down Gate, Peterborough, PE3\",\"urls\":{\"udprn\":\"/v1/udprn/18494340\"},\"udprn\":18494340},{\"suggestion\":\"10 Down Road, Weymouth, DT4\",\"urls\":{\"udprn\":\"/v1/udprn/7564526\"},\"udprn\":7564526},{\"suggestion\":\"10 Down Road, Plymouth, PL7\",\"urls\":{\"udprn\":\"/v1/udprn/19004519\"},\"udprn\":19004519},{\"suggestion\":\"10 Down Road, Guildford, GU1\",\"urls\":{\"udprn\":\"/v1/udprn/10082680\"},\"udprn\":10082680},{\"suggestion\":\"10 Down Street, Leicester, LE4\",\"urls\":{\"udprn\":\"/v1/udprn/13167602\"},\"udprn\":13167602},{\"suggestion\":\"10 Down Terrace, Brighton, BN2\",\"urls\":{\"udprn\":\"/v1/udprn/2257400\"},\"udprn\":2257400},{\"suggestion\":\"10 Down Royal, Lisburn, BT28\",\"urls\":{\"udprn\":\"/v1/udprn/3350898\"},\"udprn\":3350898}]},\"code\":2000,\"message\":\"Success\"},\"recordId\":null}",
        "NavigateToPageNo": null
    },
    "Message": null,
    "IsSuccess": true,
    "ClientScript": null,
    "Serialized": null,
    "ErrorCode": 0
}

In addition, the below methods can be combined to narrow down the search results.

Address and Postal Code Search

Returns the complete list of addresses for a postcode. By combining the two methods, the results returned are more accurate.

Call Example

Request:

Copy

{
    "ApiInfo": {
        "Token": "{{access_token}}"
    },
    "Request": {
        "ActionName": "FTOS_EXTD_POST_AddressesSearch", 
        "Data": "{ \"query\" : { postcode: \"SW1A2AA\" }   }"
    }
}

Response:

Copy

{
    "UIResult": {
        "NavigateToEntityPage": false,
        "NavigateToEntityPageOnEdit": false,
        "NavigateToEntityFormName": null,
        "NavigateToEntityName": null,
        "NavigateToEntityId": null,
        "NavigateToEntityInsertDefaults": null,
        "NavigateToUrl": null,
        "DownloadFile": null,
        "ReloadPage": false,
        "Message": null,
        "IsSuccess": false,
        "Data": "{\"response\":{\"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,\"umprn\":\"\",\"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\"}],\"code\":2000,\"message\":\"Success\",\"total\":1,\"page\":0,\"limit\":100},\"pcSearchLookupId\":\"5af051d6-d1ed-4eca-acd6-fe34b9f9f6be\",\"status\":true}",
        "NavigateToPageNo": null
    },
    "Message": null,
    "IsSuccess": true,
    "ClientScript": null,
    "Serialized": null,
    "ErrorCode": 0
}

Address and Filters Search

Returns a more accurate search list by limiting address suggestions against a list of any filter such as country, town, and others. Multiple filters can be combined.

Call Example

Request:

Copy

{
    "ApiInfo": {
        "Token": "{{access_token}}"
    },
    "Request": {
        "ActionName": "FTOS_EXTD_POST_AddressesSearch", 
        "Data": "{ \"query\" : {   address: \"street\" , filters:{limit: 1, bias_postcode_area: \"SW\"}    }   }"
    }
}

Response:

Copy

{
    "UIResult": {
        "NavigateToEntityPage": false,
        "NavigateToEntityPageOnEdit": false,
        "NavigateToEntityFormName": null,
        "NavigateToEntityName": null,
        "NavigateToEntityId": null,
        "NavigateToEntityInsertDefaults": null,
        "NavigateToUrl": null,
        "DownloadFile": null,
        "ReloadPage": false,
        "Message": null,
        "IsSuccess": false,
        "Data": "{\"response\":{\"result\":{\"total\":1,\"limit\":10,\"page\":0,\"hits\":[{\"postcode\":\"SW1A 2AA\",\"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,\"umprn\":\"\",\"postcode_type\":\"L\",\"su_organisation_indicator\":\"\",\"delivery_point_suffix\":\"1A\",\"postcode_inward\":\"2AA\",\"postcode_outward\":\"SW1A\",\"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\"}]},\"code\":2000,\"message\":\"Success\"},\"pcSearchLookupId\":\"a46fa77f-4681-412f-b828-122561d6be7b\",\"status\":true}",
        "NavigateToPageNo": null
    },
    "Message": null,
    "IsSuccess": true,
    "ClientScript": null,
    "Serialized": null,
    "ErrorCode": 0
}