Localization API

The localization API returns localization data that contains country specifics, currencies, and exchange rates as well as country-specific address field labels, field show or hide, and field require flags.

With the results of this API endpoint, you can show prices on your site in your visitor’s foreign currency and display the shipping and address fields in your checkout localized to their country.

For example, the Canary Islands do not use the city field; they only have an island. For the Canary Islands, you would hide the city field and rename the state field to “Island”.

Service endpoint – localization

HTTPS request

Information Detail
HTTP method GET
Endpoint URL https://test-api.iglobalstores.com/2.0/localization
Protocol HTTPS
Message format JSON
Accept HTTP header Accept: application/json
Security token HTTP header serviceToken: your-test-token-value
  Add a header to your HTTPS request named serviceToken with a value of your test security API token. (Contact your Account Manager for this token.)

Request parameters

None for this endpoint!

HTTPS response

Message format: JSON

Example response for only Canada & Australia; actual responses will contain all supported countries.

{
    "countries": {
        "CA": {
            "name": "Canada",
            "code": "CA",
            "currency": "CAD"
        },
        "AU": {
            "name": "Australia",
            "code": "AU",
            "currency": "AUD"
        }
    },
    "exchangeRates": {
        "CAD": {
            "rateEstimate": 1.0312,
            "rateGuaranteed": null,
            "rateGuaranteedId": null
        },
        "AUD": {
            "rate": 1.1201,
            "rateGuaranteed": null,
            "rateGuaranteedId": null
        }
    },
    "addressFields" : {
        "CA": {
            "countryCode": "CA",
            "nameLabel": "First & Last Name",
            "address1Label": "Street Address",
            "address2Label": "",
            "address3Label": "",
            "cityLabel": "City",
            "stateLabel": "Province",
            "zipLabel": "Postal Code",
            "address1Required": true,
            "address2Required": false,
            "address3Required": false,
            "cityRequired": true,
            "stateRequired": true,
            "zipRequired": true,
            "address1Show": true,
            "address2Show": true,
            "address3Show": false,
            "cityShow": true,
            "stateShow": true,
            "zipShow": true,
            "zipRegex": "[ABCEGHJKLMNPRSTVXY]\d[ABCEGHJ-NPRSTV-Z][ ]?\d[ABCEGHJ-NPRSTV-Z]\d",
            "zipFormat": "A9A 9A9",
            "regions": {
                "Alberta": {
                    "magentoCode": "66",
                    "code": "AB"
                },
                "British Columbia": {
                    "magentoCode": "67",
                    "code": "BC"
                },
                "Manitoba": {
                    "magentoCode": "68",
                    "code": "MB"
                },
                "New Brunswick": {
                    "magentoCode": "70",
                    "code": "NB"
                },
                "Newfoundland and Labrador": {
                    "magentoCode": "69",
                    "code": "NL"
                },
                "Northwest Territories": {
                    "magentoCode": "72",
                    "code": "NT"
                },
                "Nova Scotia": {
                    "magentoCode": "71",
                    "code": "NS"
                },
                "Nunavut": {
                    "magentoCode": "73",
                    "code": "NU"
                },
                "Ontario": {
                    "magentoCode": "74",
                    "code": "ON"
                },
                "Prince Edward Island": {
                    "magentoCode": "75",
                    "code": "PE"
                },
                "Quebec": {
                    "magentoCode": "76",
                    "code": "QC"
                },
                "Saskatchewan": {
                    "magentoCode": "77",
                    "code": "SK"
                },
                "Yukon Territory": {
                    "magentoCode": "78",
                    "code": "YT"
                }
            }
        },
        "AU": {
            "countryCode": "AU",
            "nameLabel": "First & LastName",
            "address1Label": "Street Address",
            "address2Label": "",
            "address3Label": "",
            "cityLabel": "City",
            "stateLabel": "State or Territory",
            "zipLabel": "Postal Code",
            "address1Required": true,
            "address2Required": false,
            "address3Required": false,
            "cityRequired": true,
            "stateRequired": true,
            "zipRequired": true,
            "address1Show": true,
            "address2Show": true,
            "address3Show": false,
            "cityShow": true,
            "stateShow": true,
            "zipShow": true,
            "zipRegex": "\d{4}",
            "zipFormat": "9999",
            "regions": {
                "Australian Capital Territory": {
                    "magentoCode": null,
                    "code": "ACT"
                },
                "New South Wales": {
                    "magentoCode": null,
                    "code": "NSW"
                },
                "Northern Territory": {
                    "magentoCode": null,
                    "code": "NT"
                },
                "Queensland": {
                    "magentoCode": null,
                    "code": "QLD"
                },
                "South Australia": {
                    "magentoCode": null,
                    "code": "SA"
                },
                "Tasmania": {
                    "magentoCode": null,
                    "code": "TAS"
                },
                "Victoria": {
                    "magentoCode": null,
                    "code": "VIC"
                },
                "Western Australia": {
                    "magentoCode": null,
                    "code": "WA"
                }
            }
        }
    }
}

Response JSON definitions

countries

This is a map with the keys being two-character country codes and the values being maps containing the name, code, and currency code of the specific country.

countries[country_code].name

Example values: ‘Canada’ or ‘Australia’

The display name for the given country.

countries[country_code].code

Example values: ‘CA’ or ‘AU’

Two-character country code of the given country, stored inside the country-specific map for convenience; also stored as the key used to retrieve the country-specific map.

countries[country_code].currency

Example values: ‘CAD’, ‘AUD’, or ‘USD’ (for some countries, it is best to use USD due to their currency fluctuating in value too dramatically)

The two-character currency code to use with this country.

exchangeRates

This is a map with the keys being three-character currency codes and the values being maps containing the rateEstimate, rateGuaranteed, and rateGuaranteedId.

exchangeRates[currency_code].rateEstimate

Example values: 1.0312 or 0.8501 (Rates may contain up to 6 digits of precision, i.e. 1.123456)

The rate to multiply by to convert USD to the specific currency for estimated foreign pricing. You would use this rate when you intend to charge the customer in USD, but show prices localized to their foreign currency.

For example, $10.00 (price in USD) multiplied by 1.0312 (the rate given for CAD) = $10.31 CAD (price in CAD rounded using the “half up” method).

exchangeRates[currency_code].rateGuaranteed

Example values: 1.0312 or 0.8501 or null (Rates may contain up to 6 digits of precision, i.e. 1.123456)

The rate to multiply by to convert USD to the specific currency for guaranteed foreign pricing. You would use this rate when you intend to charge the customer in the foreign currency using the Zonos Payment Service. This rate may be null if you are not set up to take payments through the Zonos Payment Service.

How To Use - For example, $10.00 (price in USD) multiplied by 1.0312 (the rate given for CAD) = $10.31 CAD (price in CAD rounded using the “half up” method)

exchangeRates[currency_code].rateGuaranteedId

Example values: ‘4a792a6d-a31a-4a7c-9bca-11dcb0d7a769’ or null

If rateGuaranteed is present, then this field will contain an ID to identify the guaranteed rate, for use when processing payments through the Zonos Payments Service. Otherwise, this field will be null.

addressFields

This is a map with the keys being two-character country codes and the values being maps containing the labels, show flags, and required flags for standard address fields.

addressFields[country_code].countryCode

Example values: ‘CA’ or ‘AU’

Two-character country code of the given country. Stored inside the country-specific map for convenience; also stored as the key used to retrieve the country-specific map.

addressFields[country_code].nameLabel

(Also describes these similar fields: address1Label, address2Label, address3Label, cityLabel, stateLabel, zipLabel)

Example values: ‘Full Name’ or ‘Address Line 1’ or ‘City’ or ‘Island’ or ‘Postal Code’ or null

This is the label to show the shopper for the given address field. This field may be null if the given address field is flagged to not be shown.

How To Use - If the field addressFields[country_code].stateLabel contained the value ‘Island’ then the following HTML would be appropriate for displaying a label for a state input box in an address form:

<label for="stateAddressBox">Island</label> <input id="stateAddressBox" type="text"/> addressFields[country_code].address1Required

(also describes these similar fields: address2Required, address3Required, cityRequired, stateRequired, zipRequired)

Example values: true or false

This field designates whether address1 is a required address field for the given country. If address1Required has a value of false, it does not need to be filled in to form a complete address for the given country.

How To Use - Your address validation code, both on the client and on the server, will need to take into account whether specific address fields are required for the shopper’s specific country. Other countries will not require all address fields that the US requires for a complete address.

addressFields[country_code].address1Show

(also describes these similar fields: address2Show, address3Show, cityShow, stateShow, zipShow)

Example values: true or false

This field designates whether address1 should be shown to the shopper to fill in for the given country. If address1Show has a value of false, you should not show the Address1 input field to the shopper; it is not a valid address field for the specified country.

How To Use - Only show address input fields that have a value of true in their corresponding address1Show (or like) field.

addressFields[country_code].zipRegex

Example values: ‘AD\d{3}’ or ‘([A-HJ-NP-Z])?\d{4}([A-Z]{3})?’

This field returns a regular expression string to validate a zip code input for this country.

How To Use - Your address validation code should validate the zip code input against the provided zipRegex parameter.

addressFields[country_code].zipFormat

Example values: ‘AD999’ or ‘A9999AAA’

This field returns a string example of a valid zip code for this country.

How To Use - This string can be used to provide the customer an example of a zip code that can pass validation by the zipRegex.

addressFields[country_code].regions

This is a map with the keys being the display names of the regions in that country. If the map is null, then region is not required.

addressFields[country_code].regions[region_name].code

Example value: ‘AB’

This field returns a string, representing the Zonos region code for the specified country region.

addressFields[country_code].regions[region_name].magentoCode

Example value: ‘66’

This field returns a string, representing the Magento region code for the selected country region.