1.6.2 • Public • Published


    Build, test and release

    The Firstclasspostcodes Javascript library is compatible with both Node.JS and Browsers.

    The library will work in all modern browsers and IE9+.

    An identical API is provided for both the client and server side.


    See @firstclasspostcodes/js API docs for detailed usage and examples.


    Install the package with:

    npm install @firstclasspostcodes/js

    or directly in HTML with:

    <script src="https://js.firstclasspostcodes.com/v1.6.2.js"></script>

    Note on older browsers: We recommend using a polyfill service, the following example covers all of the required language features:

    <script src="https://polyfill.io/v3/polyfill.min.js?features=Promise%2Cfetch%2CObject.assign"></script>


    Where the libary is loaded on pages including sensitive information, we recommend using the Subresource Integrity security feature.

    Every version of the library is accompanied by an SRI hash file, the hash can be accessed directly using:

    $ curl https://js.firstclasspostcodes.com/v1.6.2.sri.txt # => "sha256-45tfd... sha384-43567ytr..." 

    You can then update the above <script> tag, adding the integrity attribute:

    <script src="https://js.firstclasspostcodes.com/v1.6.2.js"
            integrity="sha256-45tfd... sha384-43567ytr..."


    You need to configure the library to use your API Key which is available on your dashboard. Require the library using the key:

    const client = require('@firstclasspostcodes/js')('fg3rfgy3345tgfAt3r');
    const postcodeData = await client.getPostcode('sw13 8gh');

    Using ES modules looks a little different:

    import Firstclasspostcodes from '@firstclasspostcodes/js';
    const client = Firstclasspostcodes('fg3rfgy3345tgfAt3r');
    // ...


    The library can be initialized with several options:

    const client = Firstclasspostcodes('fg3r...', {
      endpoint: 'https://api.firstclasspostcodes.com/data',
      content: 'json',
    Property Default Description
    endpoint https://api.firstclasspostcodes.com/data The endpoint to be used. This can be overridden to use a private endpoint, or for testing purposes.
    content 'json' The content key controls the type of response being received. geo+json can be used to receives responses in GeoJSON.


    Event handlers can be attached to the library using the Node.JS EventEmitter pattern.

    The library does not currently support wildcards or regular expressions.

    const client = Firstclasspostcodes('....');
    const handler = (requestObj) => {
    client.on('request', handler);
    client.once('response', (responseObj) => {
    client.off('request', handler);
    Event name Description
    request Triggered before a request is sent. The request object to be sent is passed to the event handler.
    response Triggered with the parsed JSON response body upon a successful reques.
    error Triggered with a client error when the request fails.
    operation:{name} Triggered by an operation with the parameter object.

    Note: {name} is replaced with the operation name of the method, as defined inside the OpenAPI specification.


    Once the library has been initialized, various debug statements are logged as requests are sent and responses received.

    Enabling debug mode:

    const client = Firstclasspostcodes('....');
    client.debugging = true;

    Integration / Testing

    We provide a mock service of our API as a docker container available here. Once the container is running, the library can be easily configured to use it:

    const Firstclasspostcodes = require('@firstclasspostcodes/js')
    const MOCK_API_URL = 'http://localhost:3000';
    // The mock API key is always 111111111111 ("12x1")
    const MOCK_API_KEY = '111111111111'
    const client = Firstclasspostcodes(MOCK_API_KEY, {
      endpoint: MOCK_API_URL,


    Run all linting and tests:

    $ npm ci
    $ npm run lint
    $ npm test

    We use Cypress to ensure that our library is working correctly inside the browser, this can be executed locally using:

    $ npm run cypress


    npm i @firstclasspostcodes/js

    DownloadsWeekly Downloads






    Unpacked Size

    322 kB

    Total Files


    Last publish


    • davidkelley