Reverse Geocoding API Documentation

Convert coordinates to addresses

The Swiftcomplete Reverse Geocoding API converts latitude longitude coordinates into readable locations or addresses.

If you would like any help or have any questions about the Reverse Geocoding API, get in touch and one of our product experts will guide you through the process of building an integration.

In this documentation:

Data Types Data Coverage Authentication Integration Options API Integration npm Package

Data Types

The Swiftcomplete Reverse Geocoding API contains address points at different resolutions or levels of accuracy, depending on the datasets that are available.

This enables us to provide full coverage for every country that we feature (see our current data coverage).

For some countries, we have a mix of Exact Address Points and Interpolated Address Points. The service always prioritises the best quality datasets, giving you the best possible results.

Exact Address Points

Exact Address Points are the most accurate dataset, containing coordinates for each invividual address.

Interpolated Address Points

Interpolated Address Points estimate a house number by dividing a street into equal sized plots based on the number of addresses on the street.

Interpolated Address Points provide a good estimation of an address and work well in urban locations where house plots are similar sizes.

Data Coverage

The following countries are available for reverse geocoding:

Canada

Exact Address Points for approximately 50% of the population, with Interpolated Address Points covering the rest of Canada.

Great Britain

Exact Address Points for the whole of Great Britain (England, Scotland & Wales)

Authentication

Each request must be authenticated with a Reverse Geocoding API key, which you can create in your Swiftcomplete account:

1. Sign in if you're already registered, or create a Swiftcomplete account if you're new to the service.

2. Head over to the API section and create a Reverse Geocoding API Key.

Integration Options

Once you've created a Reverse Geocoding API Key, you can either build an integration from scratch using the API or get started with the npm package.

API Integration

Integrate the Swiftcomplete Reverse Geocoding API to convert coordinates into addresses. Ensure all parameters are URL encoded when calling the API.

Parameters

keystringrequired
A Reverse Geocoding API Key
searchModestringrequired
Must be set to reverseGeocode
biasTowardsstringrequired
WGS84 coordinates in the format "latitude,longitude".
distanceUnitsstringdefault: metric
Unit of measurement to display how far away the address is from your provided coordinates:
- metric
- imperial
- m
- km
- ft
- mi
groupByCompassbooleandefault: false
Prioritise addresses surrounding your coordinate in all directions, rather than just the closest. Useful to return an overview of an area and ignore several nearby addresses that are grouped together.
maxResultsintegerdefault: 1
Max number of results to return (up to 5). Note that for reverse geocoding you are billed per result, so 4 results = 4 charges.

Sample API Request

https://api.swiftcomplete.com/v1/places/?key=INSERT_KEY_HERE&searchMode=reverseGeocode&biasTowards=43.64257%2C-79.38720

API Response

primary.textstring
A simplified summary of the building and street part of the address
secondary.textstring
A simplified summary of the town and city part of the address
typestring
A hierarchical type description of the address separated by full stops:
- address.*Address level result
- road.*Street level result (no building information)
- place.settlement.*City or town level result
- place.area.postcodePostcode level result
Where it isn't possible for us to differentiate between residential and business addresses in the underlying data, results are returned as address.residential.*
geometry.centre.latfloat
Latitude of the centre point of the address
geometry.centre.lonfloat
Longitude of the centre point of the address
geometry.centre.typestring
The type of coordinate contained in geometry.centre:
- addressAn exact address point
- interpolatedaddressAn interpolated address point
distance.unitsstring
Unit of measurement to display how far away the address is from your provided coordinates
distance.measurementfloat
Distance the address is from your provided coordinates, in units specified by distance.units
distance.geometryobject
Your original coordinates
populatedRecord.linesstring[]
An array of address lines representing the postal address
populatedRecord.labelstring
Formatted postal address separated by newline characters
countryCodestring
An ISO 3166-1 alpha-2 country code

Sample API Response

[
    {
        "primary": {
            "text": "301 Front St W"
        },
        "secondary": {
            "text": "Toronto ON"
        },
        "type": "address.residential.building.data",
        "geometry": {
            "centre": {
                "lat": 43.642605,
                "lon": -79.387123,
                "type": "address"
            }
        },
        "distance": {
            "units": "m",
            "measurement": 7,
            "type": "biasTowards",
            "geometry": {
                "centre": {
                    "lat": 43.64257,
                    "lon": -79.3872
                }
            }
        },
        "populatedRecord": {
            "lines": [
                "301",
                "FRONT ST W",
                "TORONTO ON",
                "",
                "CANADA"
            ],
            "label": "301 FRONT ST W\nTORONTO ON\nCANADA"
        },
        "countryCode": "ca"
    }
]

npm Package

@swiftcomplete/reverse-geocode wraps Swiftcomplete reverse geocoding functionality into an npm package.

Install & make your first request

Install

npm install @swiftcomplete/reverse-geocode

Make request

const swiftcompleteReverseGeocoder = require('@swiftcomplete/reverse-geocode');

swiftcompleteReverseGeocoder.setAPIKey('INSERT-KEY-HERE');

(async function () {
    let results = await swiftcompleteReverseGeocoder.reverseGeocode('51.499403,-0.127362', {});

    console.log(results);
}());

reverseGeocode()

Find the nearest addresses to latitude longitude coordinates in our supported countries.

Parameters

coordinatesstringrequired
WGS84 coordinates in the format "latitude,longitude".

Options object (optional)

Customise the response by passing an optional options object. Each field is optional within the object:

distanceUnitsstringdefault: metric
Unit of measurement to display how far away the address is from your provided coordinates:
- metric
- imperial
- m
- km
- ft
- mi
groupByCompassbooleandefault: false
Prioritise addresses surrounding your coordinate in all directions, rather than just the closest. Useful to return an overview of an area and ignore several nearby addresses that are grouped together.
maxResultsintegerdefault: 1
Max number of results to return (up to 5). Note that for reverse geocoding you are billed per result, so 4 results = 4 charges.

Sample request with options object

const swiftcompleteReverseGeocoder = require('@swiftcomplete/reverse-geocode');

swiftcompleteReverseGeocoder.setAPIKey('INSERT-KEY-HERE');

(async function () {
    let results = await swiftcompleteReverseGeocoder.reverseGeocode('51.499403,-0.127362', {
        maxResults: 5,
        distanceUnits: "km"
    });

    console.log(results);
}());

Response

primary.textstring
A simplified summary of the building and street part of the address
secondary.textstring
A simplified summary of the town and city part of the address
typestring
A hierarchical type description of the address separated by full stops:
- address.*Address level result
- road.*Street level result (no building information)
- place.settlement.*City or town level result
- place.area.postcodePostcode level result
Where it isn't possible for us to differentiate between residential and business addresses in the underlying data, results are returned as address.residential.*
geometry.centre.latfloat
Latitude of the centre point of the address
geometry.centre.lonfloat
Longitude of the centre point of the address
geometry.centre.typestring
The type of coordinate contained in geometry.centre:
- addressAn exact address point
- interpolatedaddressAn interpolated address point
distance.unitsstring
Unit of measurement to display how far away the address is from your provided coordinates
distance.measurementfloat
Distance the address is from your provided coordinates, in units specified by distance.units
distance.geometryobject
Your original coordinates
populatedRecord.linesstring[]
An array of address lines representing the postal address
populatedRecord.labelstring
Formatted postal address separated by newline characters
countryCodestring
An ISO 3166-1 alpha-2 country code

Sample response

[
    {
        "primary": {
            "text": "Westminster Abbey"
        },
        "secondary": {
            "text": "London"
        },
        "type": "address.residential.building.data.emptyroad",
        "geometry": {
            "centre": {
                "lat": 51.499462,
                "lon": -0.127448,
                "type": "address"
            }
        },
        "distance": {
            "units": "m",
            "measurement": 9,
            "type": "biasTowards",
            "geometry": {
                "centre": {
                    "lat": 51.499403,
                    "lon": -0.127362
                }
            }
        },
        "populatedRecord": {
            "lines": [
                "Westminster Abbey",
                "",
                "London",
                "SW1P 3PP",
                "United Kingdom"
            ],
            "label": "Westminster Abbey\nLondon\nSW1P 3PP\nUnited Kingdom"
        },
        "countryCode":"gb"
    }
]