Skip to main content
This service provides an endpoint to Matchcode Global Services via a REST interface.

Authentication

The Matchcode Global services require authentication and authorisation. The authentication is done using an ad hoc web service which is described in the next section. The authorisation check is done in each call that is made to Matchcode as it depends on the profile and configuration id provided.

Request

The authentication credentials are sent by a GET request. Two parameters must be provided: username and password. Therefore, a request will be as follows:

Response

The authentication service response is a JSON object:
The field authenticationToken will give the guid to be used for the following calls to Matchcode. This token does not change in each web service call and is valid for the current session. The expiry time is updated in each call to any REST Matchcode service. If the expiry time is reached before any new call is made, the token is invalidated and the session terminated. A new authetication request would be needed in order to do any new Matchcode service calls. The session expiry time is organisation specific and returned as a timestamp.

Execute capture

Once an authentication token has been retrieved it can be used to call one of the Matchcode services. All the Matchcode Services offered by the SOAP interface can be also requested by this REST interface, by using the ExecuteCapture path. The Request message to be sent must be JSON. Either case, the message must meet the message structure for every service. JSON examples can be found for every specific Matchcode service. NOTE that for 15b Service Protocol Version, if “maxReturn” field (within “options” element) is not present in the Request, this field will be defaulted to 75. NOTE that from 16a Service Protocol Version on, if “maxReturn” field (within “options” element) is not present in the Request, a Bad Request (HTTP code 400) will be returned by the REST Service.

Example Requests

Two extra fields need to be provided as Header Parameters: username and authenticationToken. The query details are sent in the post section as an application/json object:

Global Addressing Request

Global Addressing Response

The result of the query is returned in another json object.
Note that the expiry time will be updated, but the new value won’t be returned in the response.

UK Address Request

This request shows requestable datasets.

UK Address Response

Multidatabase Request

Reverse lookup on UDPRN restricting fields returned to Location Intelligence BEDROOMS,BATHROOMS and FLOORS and requesting punctuation/hyphenation

Multidatabase Response