Geo Community listing

API Reference - Ideal Postcodes

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.

https://api.ideal-postcodes.co.uk/v126 endpointsapiKey authno ratings yet100.0% uptime

Bring your own key. This API needs your own API Reference - Ideal Postcodes key - get one from the provider, add it once below, and the proxy injects it on every call. Your OmniStream plan covers the unified SDK, key storage, and proxy - the provider's own rate limits still apply to your key.

This is a community listing. If you own this API, you can request ownership.

Install the SDK

npm install omnistream-sdk

import { OmniClient } from "omnistream-sdk";

const omni = new OmniClient({ token: process.env.OMNI_KEY! });

// One key reaches every API on the marketplace.
const data = await omni.call("ideal-postcodes/Addresses");

One install, one key - the same client calls every API on the marketplace.

Try it

Try itone Omni key, every API

Your Omni key

GET/addresses

api_key*

query

Specifies the address you wish to query. Query can be shortened to `q=`

limit

page

filter

lon

lat

postcode_outward

postcode

postcode_area

postcode_sector

post_town

uprn

country

postcode_type

su_organisation_indicator

box

bias_postcode_outward

bias_postcode

bias_postcode_area

bias_postcode_sector

bias_post_town

bias_thoroughfare

bias_country

bias_lonlat

26 endpoints

GET/addresses

Extract Addresses

api_key*querylimitpagefilterlonlatpostcode_outwardpostcodepostcode_areapostcode_sectorpost_townuprncountrypostcode_typesu_organisation_indicatorboxbias_postcode_outwardbias_postcodebias_postcode_areabias_postcode_sectorbias_post_townbias_thoroughfarebias_countrybias_lonlat

GET/autocomplete/addresses

Find Address

api_keyquerycontextlimitpostcode_outwardpostcodepostcode_areapostcode_sectorpost_townuprncountrypostcode_typesu_organisation_indicatorboxbias_postcode_outwardbias_postcode

Typed client (copy, no install)

ideal-postcodes.ts

/**
 * APIReferenceIdealPostcodes - generated by OmniStream from API Reference - Ideal Postcodes's OpenAPI spec.
 * One typed method per endpoint. A single Omni key reaches the API.
 */
const DEFAULT_BASE = "https://grid.skinvaults.online/v1/proxy/ideal-postcodes";

export class APIReferenceIdealPostcodesError extends Error {
  status: number;
  code?: string;
  constructor(status: number, code: string | undefined, message?: string) {
    super(message || `APIReferenceIdealPostcodes error ${status}`);
    this.name = "APIReferenceIdealPostcodesError";
    this.status = status;
    this.code = code;
  }
}

export interface APIReferenceIdealPostcodesOptions {
  baseUrl?: string;
  fetch?: typeof fetch;
  timeoutMs?: number;
}

export class APIReferenceIdealPostcodes {
  /** @param token Your OmniStream key (one key for every API). */
  constructor(private token: string, private opts: APIReferenceIdealPostcodesOptions = {}) {
    if (!token) throw new Error("APIReferenceIdealPostcodes: token is required");
  }
  rateLimit: { remainingMinute?: number; remainingDay?: number } | null = null;

  private async _request(method: string, path: string, { params, body }: { params?: Record<string, unknown>; body?: unknown } = {}): Promise<any> {
    const f = this.opts.fetch ?? globalThis.fetch;
    const url = new URL((this.opts.baseUrl ?? DEFAULT_BASE).replace(/\/+$/, "") + path);
    if (params) for (const [k, v] of Object.entries(params)) if (v != null) url.searchParams.set(k, String(v));
    const headers: Record<string, string> = { "x-omni-key": this.token };
    if (body !== undefined) headers["content-type"] = "application/json";
    const res = await f(url, { method, headers, body: body !== undefined ? JSON.stringify(body) : undefined });
    this.rateLimit = {
      remainingMinute: Number(res.headers.get("x-ratelimit-remaining-minute")) || undefined,
      remainingDay: Number(res.headers.get("x-ratelimit-remaining-day")) || undefined,
    };
    const data = await res.json().catch(() => ({}));
    if (!res.ok) throw new APIReferenceIdealPostcodesError(res.status, data?.error?.code, data?.error?.message);
    return data.data ?? data;
  }

  /** Extract Addresses */
  addresses(params: { "api_key": string; "query"?: string; "limit"?: string; "page"?: string; "filter"?: string; "lon"?: string; "lat"?: string; "postcode_outward"?: string; "postcode"?: string; "postcode_area"?: string; "postcode_sector"?: string; "post_town"?: string; "uprn"?: string; "country"?: string; "postcode_type"?: string; "su_organisation_indicator"?: string; "box"?: string; "bias_postcode_outward"?: string; "bias_postcode"?: string; "bias_postcode_area"?: string; "bias_postcode_sector"?: string; "bias_post_town"?: string; "bias_thoroughfare"?: string; "bias_country"?: string; "bias_lonlat"?: string }): Promise<any> {
    return this._request("GET", "/addresses", { params });
  }

  /** Find Address */
  addressAutocomplete(params: { "api_key"?: string; "query"?: string; "context"?: string; "limit"?: string; "postcode_outward"?: string; "postcode"?: string; "postcode_area"?: string; "postcode_sector"?: string; "post_town"?: string; "uprn"?: string; "country"?: string; "postcode_type"?: string; "su_organisation_indicator"?: string; "box"?: string; "bias_postcode_outward"?: string; "bias_postcode"?: string; "bias_postcode_area"?: string; "bias_postcode_sector"?: string; "bias_post_town"?: string; "bias_thoroughfare"?: string; "bias_country"?: string; "bias_lonlat"?: string; "bias_ip"?: string }): Promise<any> {
    return this._request("GET", "/autocomplete/addresses", { params });
  }

  /** Resolve Address (GBR) */
  resolve(params: { "address": string; "api_key"?: string }): Promise<any> {
    return this._request("GET", "/autocomplete/addresses/{address}/gbr", { params });
  }

  /** Resolve Address (USA) */
  resolveUsa(params: { "address": string; "api_key"?: string }): Promise<any> {
    return this._request("GET", "/autocomplete/addresses/{address}/usa", { params });
  }

  /** Cleanse */
  addressCleanse(body: unknown, params: { "api_key"?: string }): Promise<any> {
    return this._request("POST", "/cleanse/addresses", { body, params });
  }

  /** Email Validation */
  emailValidation(params: { "api_key": string; "query": string }): Promise<any> {
    return this._request("GET", "/emails", { params });
  }

  /** Availability */
  keyAvailability(params: { "key": string }): Promise<any> {
    return this._request("GET", "/keys/{key}", { params });
  }

  /** List */
  listConfigs(params: { "key": string; "user_token"?: string }): Promise<any> {
    return this._request("GET", "/keys/{key}/configs", { params });
  }

  /** Create */
  createConfig(body: unknown, params: { "key": string; "user_token"?: string }): Promise<any> {
    return this._request("POST", "/keys/{key}/configs", { body, params });
  }

  /** Retrieve */
  retrieveConfig(params: { "key": string; "config": string }): Promise<any> {
    return this._request("GET", "/keys/{key}/configs/{config}", { params });
  }

  /** Update */
  updateConfig(body: unknown, params: { "key": string; "config": string; "user_token"?: string }): Promise<any> {
    return this._request("POST", "/keys/{key}/configs/{config}", { body, params });
  }

  /** Delete */
  deleteConfig(params: { "key": string; "config": string; "user_token"?: string }): Promise<any> {
    return this._request("DELETE", "/keys/{key}/configs/{config}", { params });
  }

  /** Details */
  keyDetails(params: { "key": string; "user_token"?: string }): Promise<any> {
    return this._request("GET", "/keys/{key}/details", { params });
  }

  /** List */
  listLicensees(params: { "key": string; "starting_after"?: number; "user_token"?: string; "limit"?: string; "query"?: string }): Promise<any> {
    return this._request("GET", "/keys/{key}/licensees", { params });
  }

  /** Create */
  createLicensee(body: unknown, params: { "key": string; "user_token"?: string }): Promise<any> {
    return this._request("POST", "/keys/{key}/licensees", { body, params });
  }

  /** Retrieve */
  retrieveLicensee(params: { "key": string; "licensee": string; "user_token"?: string }): Promise<any> {
    return this._request("GET", "/keys/{key}/licensees/{licensee}", { params });
  }

  /** Update */
  updateLicensee(body: unknown, params: { "key": string; "licensee": string; "user_token"?: string }): Promise<any> {
    return this._request("PUT", "/keys/{key}/licensees/{licensee}", { body, params });
  }

  /** Cancel */
  deleteLicensee(params: { "key": string; "licensee": string; "user_token"?: string }): Promise<any> {
    return this._request("DELETE", "/keys/{key}/licensees/{licensee}", { params });
  }

  /** Logs (CSV) */
  keyLogs(params: { "key": string; "start"?: string; "end"?: string; "licensee"?: string }): Promise<any> {
    return this._request("GET", "/keys/{key}/lookups", { params });
  }

  /** Usage Stats */
  keyUsage(params: { "key": string; "start"?: string; "end"?: string; "tags"?: string; "licensee"?: string }): Promise<any> {
    return this._request("GET", "/keys/{key}/usage", { params });
  }

  /** Phone Number Validation */
  phoneNumberValidation(params: { "api_key": string; "query": string }): Promise<any> {
    return this._request("GET", "/phone_numbers", { params });
  }

  /** Find Place */
  findPlace(params: { "api_key": string; "query"?: string; "country_iso"?: string; "bias_country_iso"?: string; "bias_lonlat"?: string; "bias_ip"?: string }): Promise<any> {
    return this._request("GET", "/places", { params });
  }

  /** Resolve Place */
  resolvePlace(params: { "place": string; "api_key"?: string }): Promise<any> {
    return this._request("GET", "/places/${place}", { params });
  }

  /** Lookup Postcode */
  postcodes(params: { "postcode": string; "api_key"?: string; "filter"?: string; "page"?: string }): Promise<any> {
    return this._request("GET", "/postcodes/{postcode}", { params });
  }

  /** Retrieve by UDPRN */
  uDPRN(params: { "udprn": string; "api_key"?: string; "filter"?: string }): Promise<any> {
    return this._request("GET", "/udprn/{udprn}", { params });
  }

  /** Retrieve by UMPRN */
  uMPRN(params: { "umprn": string; "api_key"?: string; "filter"?: string }): Promise<any> {
    return this._request("GET", "/umprn/{umprn}", { params });
  }
}

export default APIReferenceIdealPostcodes;

Reviews

No reviews yet. Be the first to rate this API.

Frequently asked questions

Do I need an API key to use API Reference - Ideal Postcodes?

Yes. API Reference - Ideal Postcodes uses apiKey authentication, so you bring your own key from the provider. You store it once on OmniStream and the proxy injects it into every call, so your code only ever sends your Omni key.

What can you do with the API Reference - Ideal Postcodes API?

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. It exposes 26 endpoints over GET, POST, DELETE, PUT, including GET /addresses, GET /autocomplete/addresses, GET /autocomplete/addresses/{address}/gbr.

How do I call API Reference - Ideal Postcodes from Python, TypeScript, Rust or Go?

Install the OmniStream SDK for your language and call API Reference - Ideal Postcodes through it. The client is generated from this API's OpenAPI spec, so parameters and responses are fully typed, and the same client also calls every other API in the marketplace.

Is API Reference - Ideal Postcodes free to use on OmniStream?

You can start on the free plan. OmniStream charges for the unified SDK, key storage and proxy rather than for API Reference - Ideal Postcodes itself, and API Reference - Ideal Postcodes's own rate limits still apply to your provider key.