• Public
  • Public/Protected
  • All

Postcode lookup options




Optional api_key

api_key: string

Providing an api_key will overwrite the api_key embedded in the client


client: Client

Client instance

Optional filter

filter: ("id" | "dataset" | "country_iso" | "country_iso_2" | "country" | "language" | "line_1" | "line_2" | "line_3" | "post_town" | "postcode" | "county" | "county_code" | "uprn" | "udprn" | "umprn" | "postcode_outward" | "postcode_inward" | "dependant_locality" | "double_dependant_locality" | "thoroughfare" | "dependant_thoroughfare" | "building_number" | "building_name" | "sub_building_name" | "po_box" | "department_name" | "organisation_name" | "postcode_type" | "su_organisation_indicator" | "delivery_point_suffix" | "premise" | "administrative_county" | "postal_county" | "traditional_county" | "district" | "ward" | "longitude" | "latitude" | "eastings" | "northings")[]

You can reduce the size of the response payload selecting for only the attributes you want to see

  filter: ["line_1", "line_2", "line_3", "post_town", "postcode"],

Optional licensee

licensee: string

If the request is made by a licensee, this should be included here

Optional page

page: number

With multiple residence datasets, a very small number of postcodes will yield more than 100 results. In this instance, you would need to paginate through them with page


postcode: string

Postcode to query for. Space and case insensitive

Optional sourceIp

sourceIp: string

For node.js client only, you can forward an IP address to be rate limited. Useful for backend integrations where the API would only see your application server IP addresses

This header will not be applied on browser requests as IDPC-Source-IP is not listed as an allowed header

Optional tags

tags: string[]

Submit tags to annotate paid API requests for retrieve and aggregation later


  • You may only specify up to 5 tags per API request
  • Each tag must not be longer than 16 UTF-8 characters

Tagging & Metadata API Documentation

Optional timeout

timeout: number

Overwrite the default HTTP request timeout defined in client