Match

The Match endpoint allows you to send one or more addresses in a single request and match each of them against the Autoaddress address database. For each address sent, it returns:

• Match status – how well the address was matched, from Matched down to NoMatch.

• Match information – the match level achieved (for example, Building) and details of how the matched address compares to the input address.

• Original input address – the submitted address.

• Matched address – the standardized address we found.

• Additional data – any extra data requested as part of your integration, such as coordinates.

This endpoint is specifically engineered to enhance the precision of address data, facilitating a more automated and streamlined system workflow that requires minimal manual intervention.

The response is a JSON array containing one match object for each address in the request, returned in the same order as the addresses were sent. Each match object also includes the input address it relates to, so every result can be tied back to the address that was sent.

The status value tells you how well each address was matched. It is one of six values, described below from the strongest match to the weakest. Your application should use it to decide what happens next.

The address has been matched to a single, complete address in the Autoaddress database.

• Use the returned address object.

• The address object will have an id.

• May have minor amendments (formatting, casing or standardization of the address lines).

The address has been matched to a building that contains more than one address – for example, an apartment block or a multi-occupancy office building – but the unit, apartment or floor was not supplied, or the one supplied could not be matched.

• Use information.subBuilding to see whether the sub-building was missing or could not be matched.

• The returned address object identifies the building. Add the unit or apartment number and resend the address to match it to the exact unit.

The input address matches more than one address in the Autoaddress database, so a single address could not be chosen. This is common for rural addresses in Ireland, where several properties can share the same address.

• Add the Eircode and resend the address.

Some elements of the input address were matched, but one or more could not be found – for example, a street name that does not exist in the town given, or a flat number that does not exist in the building.

• Use information.matchLevel to see the level the address was matched to.

• Any elements that could not be matched are returned in address.unmatched; use information.details to see how each element of the input compares to the matched address.

• Review the address before using it, or correct the input and resend it.

The input address does not contain enough information to identify a single address – for example, matching to a street with no building number or name.

• Use information.details to identify which elements of the address are missing.

• Add the missing element, such as the building number or name, and resend the address.

The address could not be matched to any address in the Autoaddress database.

• Check the input address for errors – for example, a misspelt street or town name – and resend it.

1. Collect the addresses you want to match – for example, from your database or a file received from a third party.

2. Send them to the Match endpoint as a JSON array of address objects (limit of 25 addresses per request).

3. For each object in the response, read the status value.

4. Where the status is Matched, use the address object (and any data returned) in place of the original address.

5. For any other status, use the information object to review or correct the address, then resend it.

• Provide the country parameter so that the service does not have to infer the country from the IP address of the request.

• Use the information provided in the address object when saving an address.

• Check information.timeout for each result. A value of true means the service timed out while matching that address, so the result should not be treated as final.

The Match API is authenticated using our standard authentication method. You can either use your API key directly, or create a token and pass it in the request header. For details on how to authenticate and create a token, see our Authentication documentation.

The Match API accepts POST requests. The key and country parameters are sent in the URL query string, and the addresses to be matched are sent as a JSON array in the request body with a Content-Type of application/json.

https://api.autoaddress.com/3.0/match

The body is a JSON array of address objects. The number of addresses accepted in a single call is limited to 25. Each address object can contain the following fields:

The following request sends two addresses to be matched, authenticating with an API key in the query string:

curl --location 'https://api.autoaddress.com/3.0/match?key=YOUR_API_KEY&country=IE' \
  --header 'Content-Type: application/json' \
  --data '[
  {
    "addressLines": [
      "18 Dame Street"
    ],
    "city": "Dublin 2",
    "region": "Dublin",
    "postcode": "D02 XF59"
  },
  {
    "addressLines": [
      "36 Dame Street"
    ],
    "city": "Dublin 2",
    "region": "Dublin",
    "postcode": "D02 EF64"
  }
]'

If you are using a token instead of your API key, omit the key parameter and pass the token in the request header:

Authorization: Bearer <token>

When you call the Match endpoint, the API returns a JSON array containing one match object for each address in the request. Each match object contains details about:

• The match status.

• Match information showing the match level achieved and how the matched address compares to the input address.

• The input address, exactly as it was sent.

• The matched address.

• Any additional data requested as part of your integration, such as coordinates.

This page breaks down each field and explains its purpose.

In this example, both addresses have been matched at building level and the service returns a status of Matched for each. The data object contains the additional data enabled for the integration, including coordinates.

[
  {
    "type": "match",
    "status": "Matched",
    "information": {
      "matchLevel": "Building",
      "complete": true,
      "subBuilding": "AbsentOptional",
      "details": {
        "organization": "None",
        "street": "Unchanged",
        "addressLines": "Unchanged",
        "subBuildingNumber": "None",
        "buildingNumber": "Unchanged",
        "city": "Unchanged",
        "region": "Unchanged",
        "postcode": "Unchanged"
      },
      "timeout": false
    },
    "input": {
      "lines": [
        {
          "key": "AddressLine1",
          "value": "18 Dame Street"
        }
      ],
      "city": {
        "value": "Dublin 2"
      },
      "region": {
        "value": "Dublin"
      },
      "postcode": {
        "value": "D02 XF59"
      },
      "country": {
        "language": "en",
        "value": "Ireland",
        "iso": "IE"
      },
      "label": [
        "18 Dame Street",
        "Dublin 2",
        "D02 XF59"
      ]
    },
    "address": {
      "id": "IE1400883651",
      "language": "en",
      "charset": "Latn",
      "variation": "G",
      "lines": [
        {
          "key": "Organization",
          "value": ""
        },
        {
          "key": "AddressLine1",
          "value": "18 Dame ST"
        }
      ],
      "city": {
        "value": "Dublin 2"
      },
      "region": {
        "value": "Co. Dublin"
      },
      "postcode": {
        "value": "D02 XF59"
      },
      "country": {
        "language": "en",
        "value": "Ireland",
        "iso": "IE"
      },
      "unmatched": [],
      "label": [
        "18 Dame Street",
        "Dublin 2",
        "D02 XF59"
      ]
    },
    "data": {
      "location": {
        "latitude": 53.344051,
        "longitude": -6.26498,
        "crs": "EPSG:4258",
        "accuracy": "BUILDING"
      },
      "gb_identifiers": null,
      "gb_location": null,
      "ie_admin": {
        "smallAreaId_2022": 775,
        "smallAreaId_2017": 13133,
        "smallAreaId_2015": 6374,
        "laId_2022": 29,
        "laId_2017": 29,
        "laId_2015": 29,
        "leaId_2019": 13260425,
        "leaId_2018": 13260425,
        "dedId_2022": 1831,
        "dedId_2017": 268140,
        "dedId_2015": 268140,
        "countyId": 1001000025,
        "gaeltacht": false
      },
      "ie_building": {
        "ecadId": 1400883651,
        "buildingTypeId": 3,
        "underConstruction": false,
        "buildingUse": "C",
        "vacant": false
      },
      "ie_postaladdress": null,
      "ie_geographicaddress": null,
      "ie_location": {
        "ing": {
          "easting": 315604.83,
          "northing": 234024.11,
          "crs": "EPSG:29903"
        },
        "itm": {
          "easting": 715530.52,
          "northing": 734050.41,
          "crs": "EPSG:2157"
        },
        "accuracy": 1
      },
      "ie_geodirectory": {
        "addressReference": null,
        "id": "B:50061931"
      },
      "lookup": []
    },
    "links": []
  },
  {
    "type": "match",
    "status": "Matched",
    "information": {
      "matchLevel": "Building",
      "complete": true,
      "subBuilding": "AbsentOptional",
      "details": {
        "organization": "None",
        "street": "Unchanged",
        "addressLines": "Unchanged",
        "subBuildingNumber": "None",
        "buildingNumber": "Unchanged",
        "city": "Unchanged",
        "region": "Unchanged",
        "postcode": "Unchanged"
      },
      "timeout": false
    },
    "input": {
      "lines": [
        {
          "key": "AddressLine1",
          "value": "36 Dame Street"
        }
      ],
      "city": {
        "value": "Dublin 2"
      },
      "region": {
        "value": "Dublin"
      },
      "postcode": {
        "value": "D02 EF64"
      },
      "country": {
        "language": "en",
        "value": "Ireland",
        "iso": "IE"
      },
      "label": [
        "36 Dame Street",
        "Dublin 2",
        "D02 EF64"
      ]
    },
    "address": {
      "id": "IE1702105452",
      "language": "en",
      "charset": "Latn",
      "variation": "G",
      "lines": [
        {
          "key": "Organization",
          "value": ""
        },
        {
          "key": "AddressLine1",
          "value": "36 Dame ST"
        }
      ],
      "city": {
        "value": "Dublin 2"
      },
      "region": {
        "value": "Co. Dublin"
      },
      "postcode": {
        "value": "D02 EF64"
      },
      "country": {
        "language": "en",
        "value": "Ireland",
        "iso": "IE"
      },
      "unmatched": [],
      "label": [
        "36 Dame Street",
        "Dublin 2",
        "D02 EF64"
      ]
    },
    "data": {
      "location": {
        "latitude": 53.344077,
        "longitude": -6.263001,
        "crs": "EPSG:4258",
        "accuracy": "BUILDING"
      },
      "gb_identifiers": null,
      "gb_location": null,
      "ie_admin": {
        "smallAreaId_2022": 775,
        "smallAreaId_2017": 13133,
        "smallAreaId_2015": 6374,
        "laId_2022": 29,
        "laId_2017": 29,
        "laId_2015": 29,
        "leaId_2019": 13260425,
        "leaId_2018": 13260425,
        "dedId_2022": 1831,
        "dedId_2017": 268140,
        "dedId_2015": 268140,
        "countyId": 1001000025,
        "gaeltacht": false
      },
      "ie_building": {
        "ecadId": 1401187516,
        "buildingTypeId": 3,
        "underConstruction": false,
        "buildingUse": "C",
        "vacant": true
      },
      "ie_postaladdress": null,
      "ie_geographicaddress": null,
      "ie_location": {
        "ing": {
          "easting": 315736.56,
          "northing": 234030.18,
          "crs": "EPSG:29903"
        },
        "itm": {
          "easting": 715662.22,
          "northing": 734056.48,
          "crs": "EPSG:2157"
        },
        "accuracy": 1
      },
      "ie_geodirectory": {
        "addressReference": null,
        "id": "B:50645890"
      },
      "lookup": []
    },
    "links": []
  }
]

Each object in the response array contains the following fields:

The status field tells you how well the address was matched. It can return with one of the following:

Detailed information on the quality of the match for the address object.

The details object contains an entry for each element of the address, showing how the matched address compares to the input address.

Each element has one of the following values:

Represents exactly what was sent to the API. The country object reflects the country used for the match – either the country parameter or, if it was not provided, the country inferred from the IP address of the request.

The standardized, matched address. The lines, city, region, postcode and country fields are returned as per the settings in My Form in the Account Centre, so the address object works the same as in your existing integration.

Contains additional location, administrative, building, and address reference data. The fields returned depend on the Return Data settings for your integration in the Account Centre and work the same as in your existing integration. See Return Data Settings for a full details.