Skip to main content

Address lookup

The primary method of working with addresses in EVA for billing and shipping is through the address book. A user (customer) can retrieve their address book using EVA.Core.ListAddressBook. The address book data looks like this:

export interface AddressDto {  /**   * Entity type: Address   */  ID: number;  FirstName?: string;  LastName?: string;  /**   * @deprecated Use `Address1`   */  Street?: string;  HouseNumber?: string;  Address1?: string;  Address2?: string;  ZipCode?: string;  Subdistrict?: string;  District?: string;  City?: string;  State?: string;  Region?: string;  CountryID?: string;  Latitude?: number;  Longitude?: number;  PhoneNumber?: string;  EmailAddress?: string;}

EVA support 2 ways of lookup addresses:

  • by postal code and house number (Netherlands)
  • autocomplete search (powered by Google)
{  "ZipCode": "1313AK",  "HouseNumber": "1"}

Which would give the following response:

{  "Result": {    "Street": "Cypergrasweg",    "HouseNumber": "1",    "ZipCode": "1313 AK",    "City": "Almere",    "CountryID": "NL"  }}

This is a 2-step approach where you first perform a search using EVA.Core.AutocompleteAddress and then retrieve the address details using EVA.Core.GetAutocompleteAddressByReference. Below are the example requests and responses:

{  "Query": "Buckingham"}
{  "Result": [    {      "Reference": "EitMYWFuIHZhbiBCdWNraW5naGFtLCBIb29mZGRvcnAsIE5ldGhlcmxhbmRzIi4qLAoUChIJxUfq8-fnxUcRmvG_o0B6SRgSFAoSCQ3mmqWv58VHEYM-CScGgxE_",      "Description": "Laan van Buckingham, Hoofddorp, Netherlands"    },    {      "Reference": "ChIJC-pohZPmxkcR3Be7yVF3UNE",      "Description": "Vertaalbureau Buckingham, Lariestraat, Schijndel, Netherlands"    },    {      "Reference": "ChIJb2PGY9DSt0cRgQz7mJ6oZfQ",      "Description": "Buckingham B.V., Torenstraat, Scheemda, Netherlands"    }  ]}

After selecting one of the options you can fetch the address details as follows:

{  "Suggestion": {    "Reference": "EitMYWFuIHZhbiBCdWNraW5naGFtLCBIb29mZGRvcnAsIE5ldGhlcmxhbmRzIi4qLAoUChIJxUfq8-fnxUcRmvG_o0B6SRgSFAoSCQ3mmqWv58VHEYM-CScGgxE_",    "Description": "Laan van Buckingham, Hoofddorp, Netherlands"  }}
{  "Result": {    "Formatted": "Laan van Buckingham, 2135 AA Hoofddorp, Netherlands",    "Components": [      {        "LongName": "Laan van Buckingham",        "ShortName": "Laan van Buckingham",        "Types": [          "route"        ]      },      {        "LongName": "Hoofddorp",        "ShortName": "Hoofddorp",        "Types": [          "locality",          "political"        ]      },      {        "LongName": "Haarlemmermeer",        "ShortName": "Haarlemmermeer",        "Types": [          "administrative_area_level_2",          "political"        ]      },      {        "LongName": "Noord-Holland",        "ShortName": "NH",        "Types": [          "administrative_area_level_1",          "political"        ]      },      {        "LongName": "Netherlands",        "ShortName": "NL",        "Types": [          "country",          "political"        ]      },      {        "LongName": "2135 AA",        "ShortName": "2135 AA",        "Types": [          "postal_code"        ]      }    ],    "Geometry": {      "Location": {        "Latitude": 52.2913231,        "Longitude": 4.653931099999999      }    },    "UtcOffset": 120.0,    "Street": {      "LongName": "Laan van Buckingham",      "ShortName": "Laan van Buckingham",      "Types": [        "route"      ]    },    "City": {      "LongName": "Hoofddorp",      "ShortName": "Hoofddorp",      "Types": [        "locality",        "political"      ]    },    "Region": {      "LongName": "Noord-Holland",      "ShortName": "NH",      "Types": [        "administrative_area_level_1",        "political"      ]    },    "District": {      "LongName": "Haarlemmermeer",      "ShortName": "Haarlemmermeer",      "Types": [        "administrative_area_level_2",        "political"      ]    },    "Country": {      "LongName": "Netherlands",      "ShortName": "NL",      "Types": [        "country",        "political"      ]    },    "PostalCode": {      "LongName": "2135 AA",      "ShortName": "2135 AA",      "Types": [        "postal_code"      ]    },    "IsValidCountry": true  }}

Below is some example code for extracting the required information from this response:

import { get } from 'lodash';
const addressDetails: EVA.Core.AddressSuggestionDetails = addressResult.Result;
const countryID = get(addressDetails, 'Country.ShortName', '');const streetLongName = get(addressDetails, 'Street.LongName', '');const address1 = get(addressDetails, 'HouseNumber.LongName', '') + (streetLongName ? ` ${streetLongName}` : '');const street = get(addressDetails, 'Street.LongName', '');const houseNumber = get(addressDetails, 'HouseNumber.LongName', '');const city = get(addressDetails, 'City.LongName', '');const zipCode = get(addressDetails, 'PostalCode.LongName', '');const region = get(addressDetails, 'Region.LongName', '');

Configuration options for addresses#

The use of addresses differs per country. The following EVA.Core.GetApplicationConfiguration values apply to this specifically:

  • Addresses:Address2VisibleCountries
  • Addresses:HouseNumberVisibleCountries
  • Addresses:HouseNumberRequiredCountries
  • Addresses:CityOptionalCountries
  • Addresses:StateVisibleCountries
  • Addresses:StateLength2Countries
  • Addresses:StateLength3Countries
  • Addresses:ZipCodeOptionalCountries

For more details about all the available address configuration values and what they do see the EVA documentation

Auto-filling addresses#

The EVA backend supports auto completing of addresses using these 2 services:

  • EVA.Core.AutocompleteAddress
  • EVA.Core.GetAutocompleteAddressByReference

The AutocompleteAddress service is for searching and the GetAutocompleteAddressByReference service is used to get the details of a specific result. Those details will contain individual values for street, city, etc. When mapping an auto complete result to an address DTO we have to take the Addresses:HouseNumberRequiredCountries into consideration. If a house number is required the address DTO field for HouseNumber will be filled otherwise it will be added to Address1.

For HouseNumberRequiredCountries enabled:

  • AddressDTO.Address1 = ${result.Street}
  • AddressDTO.HouseNumber = ${result.HouseNumber}

For HouseNumberRequiredCountries disabled:

  • AddressDTO.Address1 = ${result.HouseNumber} ${result.Street}