Location

Introduction

The Location Service is responsible for the management of locations and addresses. This service provides storage of locations and country/city-specific data (such as country name, city name, zip code, etc.) which can be used to validate whether info provided in location is valid or not. Note that, location or static data is tenant-specific.

Location

A location is a particular place or position. To represent it as an address is not enough. It can be represented by a geopoint or a combination of address and geopoint.

Thus, a location could be an address and/or a geocode.

Create a location

To add a location, call the Create Location endpoint.
To update a location, call the Update Location endpoint.

The following table shows the parameters that are passed to the Create location endpoint. The Update Location endpoint takes a subset of these parameters as necessary for the update:

Request bodies are specified in JSON format. The following examples show a request body for creating a Location and a request body for updating a Location:

{
    "tags": {
        "timezone": "UTC-5: Eastern Standard Time (EST)",
    },
    "address": {
        "buildingNumber": "745-c",
        "addressLine1": "21B Old St",
        "addressLine2": "Patterson Road",
        "addressLine3": "Marylebone, NW1 6XE, UK",
        "city": "Queens",
        "state": "New York",
        "country": {
            "code": "+1",
            "name": "United States"
        },
        "zipCode": "11418"
    },
    "geolocation": {
        "lat": "40.674778",
        "long": "-73.800629"
    }
}

{
    "tags": {
        "timezone": "UTC-8: Pacific Standard Time (PST)",
    },
    "address": {
        "buildingNumber": "58-E",
        "addressLine1": "4842 Horizon Circle",
        "addressLine3": "Marylebone, NW1 6XE, UK",
        "city": "Tacoma",
        "state": "Washington",
        "zipCode": "98402"
    },
    "geolocation": {
        "lat": "47.215637",
        "long": "-122.491043"
    }
}

Country data

Country data contains- a country name, state, city, county, and zip code. One state can have multiple cities and one city can have multiple zip codes. Similarly, one zip code can have multiple cities.

Add Country

Country can be added by passing the following parameters:

To add a country, call the Create Country endpoint.
To update a country, call the Update Country endpoint.

The following table shows the parameters that are passed to the Create Country endpoint. The Update Country takes a subset of these parameters as necessary for the update:

Request bodies are specified in JSON format. The following examples show a request body for adding a country and a request body for updating a country:

{
    "countryName": "Italy",
    "city": "Castelvetro",
    "state": "Modena",
    "zipCode": "41014",
    "alias": [
        "The Boot",
        "Repubblica Italiana",
        "Kingdom of Italy",
        "Italia"
    ]
}

{
    "city": "Pontida",
    "state": "Bergamo",
    "zipCode": "24030",
}

Address

An address is a set of human-readable information used for identifying a place like a building, apartment, facility, warehouse, etc. Usually, the information is presented in a format that includes specifics like apartment number and street name, and also more general terms like city, state, and country.

There is no standardized format for address as it varies across various regions or countries. However, usually, it consists of apartment number, street name, city name, state or province, country, and special codes(postal codes) for identifying a particular region.

Location Models

The location is considered as an aggregation of address and geocode. With that, an apartment in a building has an address and geocode. The apartment number is identified by the buildingNumber in the address. Thus two apartments in a building will be distinguished by different addresses.

Location, GeoCode, and Address is defined in Location Service as:

Location:

• address: Address
• geocode: Geocode
• locationInfo: Object

GeoCode:

• Longitude (double)- The range of longitude is -180 to 180 and can be up to 6 decimal places.
• Latitude (double)- The range of latitude is -90 to 90 and can be up to 6 decimal places.

Address:

• buildingNumber (string)- Building number of the address.
• addressLine1 (string)- The street information of the address.
• addressLine2 (string)- An optional additional field for the street address.
• addressLine3 (string)- Another optional additional field for the street address of the billing address.
• county (string): County of the address.
• city (string)- The city, town, or village of the address.
• state (string)- State of the address.
• zipCode (string)- Postal code of the address.
• country (Country)- Country consists of code and name.