Location types

Location types refer to data types representing geographic information, such as a point on a map, a region, or an address. They are typically used to indicate the current location of a user or the address of a person or organization.

This summary provides an overview of the location-related types:

Location

This type represents specific geographic positions or areas, such as a point on a map or a region. It usually refers to temporary locations, such as where a user is accessing a website from, rather than permanent addresses like homes or offices.

All properties in this type are optional and represent different levels of accuracy, which may vary depending on the source of information — such as GPS or IP — and the user's privacy settings.

Generally, if more specific properties are available, less specific properties are likely to be available as well. For example, the city is usually unavailable when the state is unknown.

Properties

These are the available properties:

continent(optional)

string

The name of the continent in English. For example, "North America" or "South America".

continentCode(optional)

Continent

The continent as a two-letter code. For example, "na" for North America.

country(optional)

string

Name of the country in English. For example, "United States" or "Brazil".

countryCode(optional)

string

The country code following the ISO 3166-1 alpha-2 standard, always in lower case. For example, "us" for United States.

region(optional)

string

The name of the region in its native language. For example, "California" or "Rio de Janeiro".

regionCode(optional)

string

The code is based on the ISO 3166-2 standard or official codes whenever available, always in lowercase. For example, "ca" for California.

state(optional)

string

An alias for the region property.

stateCode(optional)

string

An alias for the regionCode property.

city(optional)

string

The name of the city in its native language. For example, "New York" or "São Paulo".

district(optional)

string

The name of the district in its native language. For example, "Manhattan" for New York City or "Zona Sul" for São Paulo City.

timeZone(optional)

string

The time zone name as specified in the IANA Time Zone Database. For example, "America/New_York" or "America/Sao_Paulo".

Address

This type represents a physical or postal location that is commonly associated with a person or organization. It is intended to represent a permanent location, such as an office or home address, as opposed to a temporary location, like a position reported by a GPS device.

Properties

These are the available properties:

street(optional)

string

The full street address. For example, "123 Main St".

city(optional)

string

The city name. For example, "New York" or "São Paulo".

district(optional)

string

The city district. For example, "Downtown".

region(optional)

string

The name of the region or state. For example, "California".

state(optional)

string

An alias for the region property.

country(optional)

string

The country identifier. For example, "US" or "United States".

We recommend using the ISO 3166-1 alpha-2 code, but the identifier format is up to the implementation and can be a code, name, or any other identifier.

postalCode(optional)

string

The postal or ZIP code. For example, "90210", "SW1A 1AA", or "12345-6789".

Continent

This type is an enumeration of the seven continents, represented as two-letter codes.

These are the possible values and what they represent: