Address Plus

Our new Address Plus API provides access to regular Royal Mail postal addresses, with coordinates for each address, plus Local authority BS7666 addresses and addresses with multiple occupants.

Caution

Some requests to this API are free, while other requests are chargeable. However, free requests are meant to be used in combination with a chargeable request. Making free requests without a succeeding chargeable request is considered an improper use of the service, and can result in account suspension.

Use with JavaScript Library

We are currently working on a brand new JavaScript library, but in the meantime you can use our new Address Plus API with our existing JavaScript library by adding the code below to your config.

requestFunction: function (c2a, elements, action, parameters, callback) {
    if (!['find', 'retrieve', 'countries'].includes(action)) return;
    const headers = { Authorization: `Bearer ${parameters.key}` };
    let url;
    switch (action) {
        case 'countries':
            url = new URL('https://api.countries.fetchify.com');
            break;
        case 'find':
            url = new URL('https://api.fetchify.com/address');
            url.search = new URLSearchParams({ query: parameters.query });
            break;
        case 'retrieve':
            url = new URL(`https://api.fetchify.com/address${parameters.id}`);
            break;
    }
    fetch(url, { headers })
        .then((response) => response.json())
        .then((response) => {
            if (response.error) c2a.error('API500');
            switch (action) {
                case 'countries':
                    const { countries } = response;
                    callback({ countries, ip_location: countries[0].code, });
                    break;
                case 'find':
                    const results = [];
                    for (i = 0; i < response.results.length; i += 1) {
                        const url = new URL(response.results[i].link);
                        results.push({
                            id: url.search,
                            count: 1,
                            labels: [
                                response.results[i].fields.postcode,
                                response.results[i].summary,
                            ],
                        });
                    }
                    callback({ results });
                    break;
                case 'retrieve':
                    if (!response.results.length) c2a.error('API500');
                    const { fields } = response.results[0];
                    callback({
                        result: {
                            line_1: fields.line_1 ? fields.line_1 : '',
                            line_2: fields.line_2 ? fields.line_2 : '',
                            locality: fields.town ? fields.town : '',
                            postal_code: fields.postcode ? fields.postcode : '',
                            post_office_reference_1: fields.uprn ? fields.uprn : '',
                            province: fields.region_name ? fields.region_name : '',
                            province_code: fields.region_code ? fields.region_code : '',
                            province_name: fields.region_name ? fields.region_name : '',
                            company_name: fields.org_name ? fields.org_name : '',
                            extra: { geolocation: { latitude: fields.latitude, longitude: fields.longitude } },
                        },
                    });
                    break;
            }
        })
        .catch(() => c2a.error('API500'));
    return true;
}

swagger