Toggle menu


The Postcode worker provides services for performing an address look-up using a UK postcode.

There are many different postcode lookup systems. Some will use an external web service, others database queries. Each of these different systems are made available to the Postcode worker as "providers". Providers are written in (server-side) JavaScript, and it is the provider that actually performs the postcode look-up. The worker itself provides a standard interface for invoking these plug-in providers.

Alongside the Postcode worker, the iCM Forms Designer includes an Address Lookup field type. This field type provides the interface into which a user can enter a postcode, perform a search, and select the relevant address from the results.

By default the lookup field performs a search using the postcodeSearch method. The addresses returned by the field are stored in a variable called FIELDNAME_ADDRESS. See postcodeSearch (postcode, provider) for more information.

Worker Configuration Properties

These are the standard configuration properties that can be set for the worker. In the majority of cases you will only need to set the defaultProvider and providers properties, the rest can be empty strings/arrays.

defaultProviderString, requiredThe name of the provider that will be used if one isn't specified in the postcode lookup request (ie if you set one here the address lookup form field will "just work")
providersArray, requiredAn array of the provider names that should be set in the postcodeSearch method call or defined in the form designer's Address Lookup field

Implementations must exist for each of the providers in the API Server's Postcode worker providers directory
providersDirString, requiredThe directory in which the pre-installed provider implementations can be found

Its default value, providers, is within the worker distribution and should not be changed

Additional properties can also be included, depending upon the provider you are using. The properties for the built-in providers are:

EndPoint_ApiClientConfigObjectIf you are using the End Point provider you can provide an apiclient configuration object (to set an apiKey, serverid, user/password etc if needed)
EndPoint_NameStringIf you are using the default End Point provider, this is the name of the End Point that will be called by it
EndPoint_WorkerStringEither ajaxlibrary or serverlibrary, depending upon where your End Point is deployed
EndPointsArray of objectsAn array of End Point provider detail objects. The properties set for each provider override those defined above
EndPoints[n].ProviderStringThe name of this provider that should be set in the postcodeSearch method call or defined in the form family's Address lookup field
EndPoints[n].EndPoint_NameStringThe name of the End Point that will be invoked when this provider is used
EndPoints[n].EndPoint_WorkerStringThe worker this End Point is deployed to
EndPoints[n].EndPoint_ApiClientConfigObjectAny configuration to supply to the End Point
IdealPostcodes_KeyStringIf using Ideal Postcodes, the API key supplied with your account
MyGovScot_callertokenStringIf using MyGovScot, the name of the user used to authorise the request
NLPGAddressDB_DatasourceStringIf using an NLPG address database, the name of the datasource to use in the query. The default datasource (usually iCM) will be used if none is specified
PostcodeAnywhere_KeyStringIf using Postcode Anywhere, the API key supplied with your account
PSMA_apikeyStringAn API key provided by GOSS so the worker can access the GOSS Postcode Lookup Service (these are unique per environment)
PSMA_urlStringThe URL of the GOSS-hosted postcode lookup service


    "name": "postcode",
    "instances": 4,
    "defaultProvider": "PSMA",
    "providers": ["Example", "EndPoint", "PSMA"],
    "EndPoint_Name": "Tests.postcodeHandler",
    "EndPoint_Worker": "serverlibrary",
    "EndPoint_ApiClientConfig": {},
    "EndPoints": [{
        "Provider": "local",
        "EndPoint_Name": "Tests.postcodeHandlerLocal",
        "EndPoint_Worker": "serverlibrary",
        "EndPoint_ApiClientConfig": {}
    }, {
        "Provider": "national",
        "EndPoint_Name": "Tests.postcodeHandlerNational",
        "EndPoint_Worker": "serverlibrary",
        "EndPoint_ApiClientConfig": {}
    "PSMA_url": "http://the-url",
    "PSMA_apikey": "17ED5F1F-XXXX-XXXX-XXXX-6D653E263AF5"

In the example configuration above, if no value is entered into the Provider property of the form designer's Address Lookup field, the "PSMA" provider will be used.

If the field has "EndPoint" set as the provider, the Tests.postcodeHandler End Point will be used.

To use the Tests.postcodeHandlerNational End Point, set the provider as "national" in the field.



This function is called to obtain a list of available postcode providers.

postcodeSearch (postcode, provider)

Searches for addresses that match a supplied postcode.

Share this page

Facebook icon Twitter icon email icon


print icon