Localization API

Returns localization data containing 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 end point, you can show prices on your site in your visitor’s foreign currency, and show the shipping and address fields in your checkout localized to their country.

For example, the Canary Islands don’t 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 End Point – localization

HTTPS Request

HTTP Method GET
End Point 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 end point!

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 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’ or ‘AUD’ or ‘USD’ (some countries it’s best to USD because their currencies fluxuate 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 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 multiple 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 currecny.

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 multiple 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 iGlobal Payment Service. This rate may be null if you are not setup to take payments through the iGlobal 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 iGlobal Payments Service. Otherwise this field will be null.

addressFields

This is a map, with the keys being two character country codes, and 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 show 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 iGlobal 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.