# API Reference - Ideal Postcodes API

> API Reference - Ideal Postcodes API on Apizie: 26 endpoints (Extract Addresses, Find Address, Resolve Address (GBR), Resolve Address (USA), …) returned as clean JSON through one API key. 26 endpoints are live now. Call it over REST at https://apizie.tech/v1/places:ideal-postcodes-co-uk/{endpoint} or from Claude, ChatGPT and Cursor through the Apizie MCP server. Free plan: 1,000 requests a month.

- Project key: `places:ideal-postcodes-co-uk`
- Category: Places
- Status: live
- Source: https://ideal-postcodes.co.uk/support
- Page: https://apizie.tech/api/places/ideal-postcodes-co-uk
- OpenAPI: https://apizie.tech/api/places/ideal-postcodes-co-uk/openapi.json

# Getting Started ## Overview ### Access 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…

## Endpoints

### Extract Addresses
`GET https://apizie.tech/v1/places:ideal-postcodes-co-uk/addresses`

| Parameter | Type | Required | Description |
|---|---|---|---|
| api_key | string | yes | Your API Key. Typically beings `ak_`. Available from your dashboard |
| query | string | no | Specifies the address you wish to query. Query can be shortened to `q=` |
| limit | integer | no | Specifies the maximum number of suggestions to retrieve. By default the limit is 10, unless a postcode is queried (then all addresses at… |
| page | integer | no | 0 indexed indicator of the page of results to receive. Virtually all postcode results are returned on page 0. A small number of Multiple… |
| filter | string | no | 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`… |
| lon | number | no | Longitude query for reverse geocoding. An accompanying latitude (lat=) query must be submitted for a valid reverse geocode query. |
| lat | number | no | Latitude query for reverse geocoding. An accompanying longitude (lon=) query must be submitted for a valid reverse geocode query. |
| postcode_outward | string | no | Filter by outward code. |
| postcode | string | no | Filter by postcode. Can be combined with query to perform a postcode + building number/name search. |
| postcode_area | string | no | Filter by postcode. Can be combined with query to perform a postcode + building number/name search. |
| postcode_sector | string | no | Filter by postcode sector, the outward code plus first numeric of the inward code. |
| post_town | string | no | Filter by town. |
| uprn | integer | no | Filters by UPRN. Does not accept comma separated terms. Only a single term is permitted |
| country | string | no | Filter by country. Possible values are England, Scotland, Wales, Northern Ireland, Jersey, Guernsey and Isle of Man. |
| postcode_type | string | no | Filter by Postcode Type. Useful for separating organisational and residential addresses |
| su_organisation_indicator | string | no | Filter by Organisation Indicator. Useful for separating organisational and residential addresses |
| box | string | no | 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 | no | Bias by outward code |
| bias_postcode | string | no | Bias by postcode. Can be combined with query to perform a postcode + building number/name search. |
| bias_postcode_area | string | no | Bias by postcode area, the first one or two non-numeric characters of a postcode. |
| bias_postcode_sector | string | no | Bias by postcode sector, the outward code plus first numeric of the inward code. |
| bias_post_town | string | no | Bias by town. |
| bias_thoroughfare | string | no | Bias by street name. |
| bias_country | string | no | Bias by country. Possible values are England, Scotland, Wales, Northern Ireland, Jersey, Guernsey and Isle of Man. |
| bias_lonlat | string | no | Bias search to a geospatial circle determined by an origin and radius in meters. Max radius is `50000`. Uses the format… |

### Find Address
`GET https://apizie.tech/v1/places:ideal-postcodes-co-uk/address-autocomplete`

| Parameter | Type | Required | Description |
|---|---|---|---|
| api_key | string | no | Your API Key. Typically beings `ak_`. Available from your dashboard |
| query | string | no | Specifies the address you wish to query. Query can be shortened to `q=` |
| context | string | no | Limits search results within a geographical boundary or country. |
| limit | integer | no | Limits number of address suggestions unless a postcode is detected. In this instance entire list of addreses for that postcode is returned. |
| postcode_outward | string | no | Filter by outward code. |
| postcode | string | no | Filter by postcode. Can be combined with query to perform a postcode + building number/name search. |
| postcode_area | string | no | Filter by postcode. Can be combined with query to perform a postcode + building number/name search. |
| postcode_sector | string | no | Filter by postcode sector, the outward code plus first numeric of the inward code. |
| post_town | string | no | Filter by town. |
| uprn | integer | no | Filters by UPRN. Does not accept comma separated terms. Only a single term is permitted |
| country | string | no | Filter by country. Possible values are England, Scotland, Wales, Northern Ireland, Jersey, Guernsey and Isle of Man. |
| postcode_type | string | no | Filter by Postcode Type. Useful for separating organisational and residential addresses |
| su_organisation_indicator | string | no | Filter by Organisation Indicator. Useful for separating organisational and residential addresses |
| box | string | no | 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 | no | Bias by outward code |
| bias_postcode | string | no | Bias by postcode. Can be combined with query to perform a postcode + building number/name search. |
| bias_postcode_area | string | no | Bias by postcode area, the first one or two non-numeric characters of a postcode. |
| bias_postcode_sector | string | no | Bias by postcode sector, the outward code plus first numeric of the inward code. |
| bias_post_town | string | no | Bias by town. |
| bias_thoroughfare | string | no | Bias by street name. |
| bias_country | string | no | Bias by country. Possible values are England, Scotland, Wales, Northern Ireland, Jersey, Guernsey and Isle of Man. |
| bias_lonlat | string | no | Bias search to a geospatial circle determined by an origin and radius in meters. Max radius is `50000`. Uses the format… |
| bias_ip | string | no | Biases search based on approximate geolocation of IP address. Set `bias_ip=true` to enable. |

### Resolve Address (GBR)
`GET https://apizie.tech/v1/places:ideal-postcodes-co-uk/resolve`

| Parameter | Type | Required | Description |
|---|---|---|---|
| address | string | yes | ID of address suggestion |
| api_key | string | no | Your API Key. Typically beings `ak_`. Available from your dashboard |

### Resolve Address (USA)
`GET https://apizie.tech/v1/places:ideal-postcodes-co-uk/resolve-usa`

| Parameter | Type | Required | Description |
|---|---|---|---|
| address | string | yes | ID of address suggestion |
| api_key | string | no | Your API Key. Typically beings `ak_`. Available from your dashboard |

### Cleanse
`POST https://apizie.tech/v1/places:ideal-postcodes-co-uk/address-cleanse`

| Parameter | Type | Required | Description |
|---|---|---|---|
| api_key | string | no | Your API Key. Typically beings `ak_`. Available from your dashboard |
| body | object | yes | JSON request body |

### Email Validation
`GET https://apizie.tech/v1/places:ideal-postcodes-co-uk/email-validation`

| Parameter | Type | Required | Description |
|---|---|---|---|
| api_key | string | yes | Your API Key. Typically beings `ak_`. Available from your dashboard |
| query | string | yes | Specifies the email address to validate |

### Availability
`GET https://apizie.tech/v1/places:ideal-postcodes-co-uk/key-availability`

| Parameter | Type | Required | Description |
|---|---|---|---|
| key | string | yes | Your API Key. Typically beings `ak_`. Available from your dashboard |

### List
`GET https://apizie.tech/v1/places:ideal-postcodes-co-uk/list-configs`

| Parameter | Type | Required | Description |
|---|---|---|---|
| key | string | yes | Your API Key. Typically beings `ak_`. Available from your dashboard |
| user_token | string | no | A secret key used for sensitive operations on your account and API Keys. Your user token can be retrieved and managed from your [accounts… |

### Create
`POST https://apizie.tech/v1/places:ideal-postcodes-co-uk/create-config`

| Parameter | Type | Required | Description |
|---|---|---|---|
| key | string | yes | Your API Key. Typically beings `ak_`. Available from your dashboard |
| user_token | string | no | A secret key used for sensitive operations on your account and API Keys. Your user token can be retrieved and managed from your [accounts… |
| body | object | yes | JSON request body |

### Retrieve
`GET https://apizie.tech/v1/places:ideal-postcodes-co-uk/retrieve-config`

| Parameter | Type | Required | Description |
|---|---|---|---|
| key | string | yes | Your API Key. Typically beings `ak_`. Available from your dashboard |
| config | string | yes | User provided configuration object name |

### Update
`POST https://apizie.tech/v1/places:ideal-postcodes-co-uk/update-config`

| Parameter | Type | Required | Description |
|---|---|---|---|
| key | string | yes | Your API Key. Typically beings `ak_`. Available from your dashboard |
| config | string | yes | User provided configuration object name |
| user_token | string | no | A secret key used for sensitive operations on your account and API Keys. Your user token can be retrieved and managed from your [accounts… |
| body | object | yes | JSON request body |

### Delete
`POST https://apizie.tech/v1/places:ideal-postcodes-co-uk/delete-config`

| Parameter | Type | Required | Description |
|---|---|---|---|
| key | string | yes | Your API Key. Typically beings `ak_`. Available from your dashboard |
| config | string | yes | User provided configuration object name |
| user_token | string | no | A secret key used for sensitive operations on your account and API Keys. Your user token can be retrieved and managed from your [accounts… |

### Details
`GET https://apizie.tech/v1/places:ideal-postcodes-co-uk/key-details`

| Parameter | Type | Required | Description |
|---|---|---|---|
| key | string | yes | Your API Key. Typically beings `ak_`. Available from your dashboard |
| user_token | string | no | A secret key used for sensitive operations on your account and API Keys. Your user token can be retrieved and managed from your [accounts… |

### List
`GET https://apizie.tech/v1/places:ideal-postcodes-co-uk/list-licensees`

| Parameter | Type | Required | Description |
|---|---|---|---|
| key | string | yes | Your API Key. Typically beings `ak_`. Available from your dashboard |
| starting_after | integer | no | Specify ID of the licensee after which you would like to list results |
| user_token | string | no | A secret key used for sensitive operations on your account and API Keys. Your user token can be retrieved and managed from your [accounts… |
| limit | integer | no | Specify the maximum number of results to return per page. Default and maximum is `100`. |
| query | string | no | Filter result by licensee name. Query can be shortened to `q=` |

### Create
`POST https://apizie.tech/v1/places:ideal-postcodes-co-uk/create-licensee`

| Parameter | Type | Required | Description |
|---|---|---|---|
| key | string | yes | Your API Key. Typically beings `ak_`. Available from your dashboard |
| user_token | string | no | A secret key used for sensitive operations on your account and API Keys. Your user token can be retrieved and managed from your [accounts… |
| body | object | yes | JSON request body |

### Retrieve
`GET https://apizie.tech/v1/places:ideal-postcodes-co-uk/retrieve-licensee`

| Parameter | Type | Required | Description |
|---|---|---|---|
| key | string | yes | Your API Key. Typically beings `ak_`. Available from your dashboard |
| licensee | string | yes | Uniquely identifies a licensee |
| user_token | string | no | A secret key used for sensitive operations on your account and API Keys. Your user token can be retrieved and managed from your [accounts… |

### Update
`POST https://apizie.tech/v1/places:ideal-postcodes-co-uk/update-licensee`

| Parameter | Type | Required | Description |
|---|---|---|---|
| key | string | yes | Your API Key. Typically beings `ak_`. Available from your dashboard |
| licensee | string | yes | Uniquely identifies a licensee |
| user_token | string | no | A secret key used for sensitive operations on your account and API Keys. Your user token can be retrieved and managed from your [accounts… |
| body | object | yes | JSON request body |

### Cancel
`POST https://apizie.tech/v1/places:ideal-postcodes-co-uk/delete-licensee`

| Parameter | Type | Required | Description |
|---|---|---|---|
| key | string | yes | Your API Key. Typically beings `ak_`. Available from your dashboard |
| licensee | string | yes | Uniquely identifies a licensee |
| user_token | string | no | A secret key used for sensitive operations on your account and API Keys. Your user token can be retrieved and managed from your [accounts… |

### Logs (CSV)
`GET https://apizie.tech/v1/places:ideal-postcodes-co-uk/key-logs`

| Parameter | Type | Required | Description |
|---|---|---|---|
| key | string | yes | Your API Key. Typically beings `ak_`. Available from your dashboard |
| start | integer | no | An start date/time in the form of a UNIX Timestamp in milliseconds, e.g. `1418556452651`. If no start time is provided, the start time… |
| end | integer | no | An end date/time in the form of a UNIX Timestamp in milliseconds, e.g. `1418556452651`. If no end time is provided, the current time will… |
| licensee | string | no | Sublicensed keys only. This will restrict the analysed dataset to a specific licensee. |

### Usage Stats
`GET https://apizie.tech/v1/places:ideal-postcodes-co-uk/key-usage`

| Parameter | Type | Required | Description |
|---|---|---|---|
| key | string | yes | Your API Key. Typically beings `ak_`. Available from your dashboard |
| start | integer | no | A start date/time in the form of a UNIX Timestamp in milliseconds, e.g. `1418556452651`. If no start time is provided, the start time will… |
| end | integer | no | An end date/time in the form of a UNIX Timestamp in milliseconds, e.g. `1418556452651`. If no end time is provided, the current time will… |
| tags | string | no | A comma separated list of tags to query over. Useful if you want to specify the circumstances in which the request was made. If multiple… |
| licensee | string | no | Sublicensed keys only. This will restrict the analysed dataset to a specific licensee. |

### Phone Number Validation
`GET https://apizie.tech/v1/places:ideal-postcodes-co-uk/phone-number-validation`

| Parameter | Type | Required | Description |
|---|---|---|---|
| api_key | string | yes | Your API Key. Typically beings `ak_`. Available from your dashboard |
| query | string | yes | Specifies the phone number to validate. Phone number must include a country code in acceptable format. For instance, UK phone numbers… |

### Find Place
`GET https://apizie.tech/v1/places:ideal-postcodes-co-uk/find-place`

| Parameter | Type | Required | Description |
|---|---|---|---|
| api_key | string | yes | Your API Key. Typically beings `ak_`. Available from your dashboard |
| query | string | no | Specifies the place you wish to query. Query can be shortened to `q=` |
| country_iso | string | no | Filter by country ISO code. Uses 3 letter country code (ISO 3166-1) standard. Filter by multiple countries with a comma separated list.… |
| bias_country_iso | string | no | 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.… |
| bias_lonlat | string | no | Bias search to a geospatial circle determined by an origin and radius in meters. Max radius is `50000`. Uses the format… |
| bias_ip | string | no | Biases search based on approximate geolocation of IP address. Set `bias_ip=true` to enable. |

### Resolve Place
`GET https://apizie.tech/v1/places:ideal-postcodes-co-uk/resolve-place`

| Parameter | Type | Required | Description |
|---|---|---|---|
| place | string | yes | ID of place suggestion |
| api_key | string | no | Your API Key. Typically beings `ak_`. Available from your dashboard |

### Lookup Postcode
`GET https://apizie.tech/v1/places:ideal-postcodes-co-uk/postcodes`

| Parameter | Type | Required | Description |
|---|---|---|---|
| postcode | string | yes | Postcode to retrieve |
| api_key | string | no | Your API Key. Typically beings `ak_`. Available from your dashboard |
| filter | string | no | 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`… |
| page | integer | no | 0 indexed indicator of the page of results to receive. Virtually all postcode results are returned on page 0. A small number of Multiple… |

### Retrieve by UDPRN
`GET https://apizie.tech/v1/places:ideal-postcodes-co-uk/udprn`

| Parameter | Type | Required | Description |
|---|---|---|---|
| udprn | string | yes | UDPRN to be retrieved |
| api_key | string | no | Your API Key. Typically beings `ak_`. Available from your dashboard |
| filter | string | no | 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`… |

### Retrieve by UMPRN
`GET https://apizie.tech/v1/places:ideal-postcodes-co-uk/umprn`

| Parameter | Type | Required | Description |
|---|---|---|---|
| umprn | string | yes | UMPRN to be retrieved |
| api_key | string | no | Your API Key. Typically beings `ak_`. Available from your dashboard |
| filter | string | no | 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`… |

## Example
```
curl "https://apizie.tech/v1/places:ideal-postcodes-co-uk/addresses" \
  -H "x-api-key: $APIZIE_KEY"
```

## FAQ

### How do I call the API Reference - Ideal Postcodes API?
Create a free Apizie key, then send GET https://apizie.tech/v1/places:ideal-postcodes-co-uk/addresses with the header x-api-key. Every endpoint returns { project, data, timestamp }.

### Is the API Reference - Ideal Postcodes API free on Apizie?
Yes. The Free plan includes 1,000 requests a month at 100 requests a minute, no credit card.

### Can AI agents use the API Reference - Ideal Postcodes API?
Yes. Add the Apizie MCP server (https://apizie.tech/mcp) to Claude, ChatGPT, Cursor or VS Code, then ask in plain language. The agent calls run_scraper with project key places:ideal-postcodes-co-uk.

### What is the status of the API Reference - Ideal Postcodes API?
Live: works with just an Apizie key