Location

Module to generate addresses and locations. Prior to Faker 8.0.0, this module was known as faker.address.

Overview

For a typical street address for a locale, use streetAddress(), city(), state(), and zipCode(). Most locales provide localized versions for a specific country.

If you need latitude and longitude coordinates, use latitude() and longitude(), or nearbyGPSCoordinate() for a latitude/longitude near a given location.

For a random country, you can use country() or countryCode().

buildingNumber

Generates a random building number.

Available since v8.0.0

Returns: string

function buildingNumber(): string;

Examples

faker.location.buildingNumber() // '379'

Source

View Source

cardinalDirection

Returns a random cardinal direction (north, east, south, west).

Available since v8.0.0

Parameters

Name	Type	Default	Description
options	{ … }	`{}`	The options to use.
options.abbreviated?	boolean	`false`	If true this will return abbreviated directions (N, E, etc). Otherwise this will return the long name.

Returns: string

function cardinalDirection(
  options: {
    abbreviated?: boolean;
  } = {}
): string;

Examples

faker.location.cardinalDirection() // 'North'
faker.location.cardinalDirection({ abbreviated: true }) // 'W'

Source

View Source

city

Generates a random localized city name.

Available since v8.0.0

Returns: string

function city(): string;

Examples

faker.location.city() // 'East Jarretmouth'
fakerDE.location.city() // 'Bad Lilianadorf'

Source

View Source

continent

Returns a random continent name.

Available since v9.1.0

Returns: string

function continent(): string;

Examples

faker.location.continent() // 'Asia'

Source

View Source

country

Returns a random country name.

Available since v8.0.0

Returns: string

function country(): string;

Examples

faker.location.country() // 'Greece'

Source

View Source

countryCode

Returns a random ISO_3166-1 country code.

Available since v8.0.0

Parameters

Name	Type	Default	Description
options	'alpha-2' \| 'alpha-3' \| 'numeric' \| { … }	`{}`	The code to return or an options object.
options.variant?	'alpha-2' \| 'alpha-3' \| 'numeric'	`'alpha-2'`	The code to return. Can be either `'alpha-2'` (two-letter code), `'alpha-3'` (three-letter code) or `'numeric'` (numeric code).

Returns: string

function countryCode(
  options:
    | 'alpha-2'
    | 'alpha-3'
    | 'numeric'
    | {
        variant?: 'alpha-2' | 'alpha-3' | 'numeric';
      } = {}
): string;

Examples

faker.location.countryCode() // 'SJ'
faker.location.countryCode('alpha-2') // 'GA'
faker.location.countryCode('alpha-3') // 'TJK'
faker.location.countryCode('numeric') // '528'

Source

View Source

county

Returns a random localized county, or other equivalent second-level administrative entity for the locale's country such as a district or department.

Available since v8.0.0

Returns: string

function county(): string;

Examples

fakerEN_GB.location.county() // 'Cambridgeshire'
fakerEN_US.location.county() // 'Monroe County'

Source

View Source

direction

Returns a random direction (cardinal and ordinal; northwest, east, etc).

Available since v8.0.0

Parameters

Name	Type	Default	Description
options	{ … }	`{}`	The options to use.
options.abbreviated?	boolean	`false`	If true this will return abbreviated directions (NW, E, etc). Otherwise this will return the long name.

Returns: string

function direction(
  options: {
    abbreviated?: boolean;
  } = {}
): string;

Examples

faker.location.direction() // 'Northeast'
faker.location.direction({ abbreviated: true }) // 'SW'

Source

View Source

language

Returns a random spoken language.

Available since v9.4.0

Returns: Language

function language(): Language;

Examples

faker.location.language() // { alpha2: 'de', alpha3: 'deu', name: 'German' }
faker.location.language().name // German
faker.location.language().alpha2 // de
faker.location.language().alpha3 // deu

Source

View Source

latitude

Generates a random latitude.

Available since v8.0.0

Parameters

Name	Type	Default	Description
options	{ … }	`{}`	An options object.
options.max?	number	`90`	The upper bound for the latitude to generate.
options.min?	number	`-90`	The lower bound for the latitude to generate.
options.precision?	number	`4`	The number of decimal points of precision for the latitude.

Returns: number

function latitude(
  options: {
    max?: number;
    min?: number;
    precision?: number;
  } = {}
): number;

Examples

faker.location.latitude() // -30.9501
faker.location.latitude({ max: 10 }) // 5.7225
faker.location.latitude({ max: 10, min: -10 }) // -9.6273
faker.location.latitude({ max: 10, min: -10, precision: 5 }) // 2.68452

Source

View Source

longitude

Generates a random longitude.

Available since v8.0.0

Parameters

Name	Type	Default	Description
options	{ … }	`{}`	An options object.
options.max?	number	`180`	The upper bound for the longitude to generate.
options.min?	number	`-180`	The lower bound for the longitude to generate.
options.precision?	number	`4`	The number of decimal points of precision for the longitude.

Returns: number

function longitude(
  options: {
    max?: number;
    min?: number;
    precision?: number;
  } = {}
): number;

Examples

faker.location.longitude() // -30.9501
faker.location.longitude({ max: 10 }) // 5.7225
faker.location.longitude({ max: 10, min: -10 }) // -9.6273
faker.location.longitude({ max: 10, min: -10, precision: 5 }) // 2.68452

Source

View Source

nearbyGPSCoordinate

Generates a random GPS coordinate within the specified radius from the given coordinate.

Available since v8.0.0

Parameters

Name	Type	Default	Description
options	{ … }	`{}`	The options for generating a GPS coordinate.
options.isMetric?	boolean	`false`	If `true` assume the radius to be in kilometers. If `false` for miles.
options.origin?	[latitude: number, longitude: number]		The original coordinate to get a new coordinate close to.
options.radius?	number	`10`	The maximum distance from the given coordinate to the new coordinate.

Returns: [latitude: number, longitude: number]

function nearbyGPSCoordinate(
  options: {
    origin?: [latitude: number, longitude: number];
    radius?: number;
    isMetric?: boolean;
  } = {}
): [latitude: number, longitude: number];

Examples

faker.location.nearbyGPSCoordinate() // [ 33.8475, -170.5953 ]
faker.location.nearbyGPSCoordinate({ origin: [33, -170] }) // [ 33.0165, -170.0636 ]
faker.location.nearbyGPSCoordinate({ origin: [33, -170], radius: 1000, isMetric: true }) // [ 37.9163, -179.2408 ]

Source

View Source

ordinalDirection

Returns a random ordinal direction (northwest, southeast, etc).

Available since v8.0.0

Parameters

Name	Type	Default	Description
options	{ … }	`{}`	Whether to use abbreviated or an options object.
options.abbreviated?	boolean	`false`	If true this will return abbreviated directions (NW, SE, etc). Otherwise this will return the long name.

Returns: string

function ordinalDirection(
  options: {
    abbreviated?: boolean;
  } = {}
): string;

Examples

faker.location.ordinalDirection() // 'Northeast'
faker.location.ordinalDirection({ abbreviated: true }) // 'SW'

Source

View Source

postalAddress

Generates a random localized full postal address, which may include a street address, secondary address, city, state, and zip code. To ensure you get locale-specific address formats, use a localized Faker instance.

Available since v10.5.0

Returns: string

function postalAddress(): string;

Examples

faker.location.postalAddress()
// 'Apt. 980
// 0917 O'Conner Estates
// West Shannonview
// Michigan
// 82180'

fakerEN_US.location.postalAddress()
// '0917 O'Conner Estates, Apt. 980
// West Shannonview, MI 82180'

fakerEN_GB.location.postalAddress()
// '79 Bogan Corner
// Castle Zemlakborough
// Dumfries and Galloway
// ZH17 2SD'

fakerZH_CN.location.postalAddress()
// '广东省贵原市门路19号'

Source

View Source

secondaryAddress

Generates a random localized secondary address. This refers to a specific location at a given address such as an apartment or room number.

Available since v8.0.0

Returns: string

function secondaryAddress(): string;

Examples

faker.location.secondaryAddress() // 'Apt. 861'

Source

View Source

state

Returns a random localized state, or other equivalent first-level administrative entity for the locale's country such as a province or region. Generally, these are the ISO 3166-2 subdivisions for a country. If a locale doesn't correspond to one specific country, the method may return ISO 3166-2 subdivisions from one or more countries that uses that language. For example, the ar locale includes subdivisions from Arabic-speaking countries, such as Tunisia, Algeria, Syria, Lebanon, etc. For historical compatibility reasons, the default en locale only includes states in the United States (identical to en_US). However, you can use other English locales, such as en_IN, en_GB, and en_AU, if needed.

Available since v8.0.0

Parameters

Name	Type	Default	Description
options	{ … }	`{}`	An options object.
options.abbreviated?	boolean	`false`	If true this will return abbreviated first-level administrative entity names. Otherwise this will return the long name.

Returns: string

function state(
  options: {
    abbreviated?: boolean;
  } = {}
): string;

Examples

faker.location.state() // 'Mississippi'
fakerEN_CA.location.state() // 'Saskatchewan'
fakerDE.location.state() // 'Nordrhein-Westfalen'
faker.location.state({ abbreviated: true }) // 'LA'

Source

View Source

street

Generates a random localized street name.

Available since v8.0.0

Returns: string

function street(): string;

Examples

faker.location.street() // 'Schroeder Isle'

Source

View Source

streetAddress

Generates a random localized street address.

Available since v8.0.0

Parameters

Name	Type	Default	Description
options	boolean \| { … }	`{}`	Whether to use a full address or an options object.
options.useFullAddress?	boolean		When true this will generate a full address. Otherwise it will just generate a street address.

Returns: string

function streetAddress(
  options:
    | boolean
    | {
        useFullAddress?: boolean;
      } = {}
): string;

Examples

faker.location.streetAddress() // '0917 O'Conner Estates'
faker.location.streetAddress(false) // '34830 Erdman Hollow'
faker.location.streetAddress(true) // '3393 Ronny Way Apt. 742'
faker.location.streetAddress({ useFullAddress: true }) // '7917 Miller Park Apt. 410'

Source

View Source

timeZone

Returns a random IANA time zone relevant to this locale.

The returned time zone is tied to the current locale.

Available since v8.0.0

Returns: string

function timeZone(): string;

Examples

faker.location.timeZone() // 'Pacific/Guam'

Source

View Source

zipCode

Generates random zip code from specified format. If format is not specified, the locale's zip format is used.

Available since v8.0.0

Parameters

Name Type Default Description

options

string | { … }

Name	Type	Default	Description
options	string \| { … }	`{}`	The format used to generate the zip code or an options object.
options.format?	string	`faker.definitions.location.postcode`	The optional format used to generate the zip code. This won't be used if the state option is specified.
options.state?	string		The state to generate the zip code for. If the current locale does not have a corresponding `postcode_by_state` definition, an error is thrown.

{}

The format used to generate the zip code or an options object.

options.format?

string

faker.definitions.location.postcode

The optional format used to generate the zip code.

This won't be used if the state option is specified.

options.state?

string

The state to generate the zip code for.

If the current locale does not have a corresponding postcode_by_state definition, an error is thrown.

Returns: string

Throws: If the locale has no zip code definition for the given state.

function zipCode(
  options:
    | string
    | {
        state?: string;
        format?: string;
      } = {}
): string;

Examples

faker.location.zipCode() // '17839'
faker.location.zipCode('####') // '6925'

Source

View Source

Location ​

Overview ​

buildingNumber ​

Examples

Source

cardinalDirection ​

Parameters

Examples

Source

city ​

Examples

Source

continent ​

Examples

Source

country ​

Examples

Source

countryCode ​

Parameters

Examples

Source

county ​

Examples

Source

direction ​

Parameters

Examples

Source

language ​

Examples

See Also

Source

latitude ​

Parameters

Examples

Source

longitude ​

Parameters

Examples

Source

nearbyGPSCoordinate ​

Parameters

Examples

Source

ordinalDirection ​

Parameters

Examples

Source

postalAddress ​

Examples

Source

secondaryAddress ​

Examples

Source

state ​

Parameters

Examples

Source

street ​

Examples

Source

streetAddress ​

Parameters

Examples

Source

timeZone ​

Examples

See Also

Source

zipCode ​

Parameters

Examples

See Also

Source

Location

Overview

buildingNumber

cardinalDirection

city

continent

country

countryCode

county

direction

language

latitude

longitude

nearbyGPSCoordinate

ordinalDirection

postalAddress

secondaryAddress

state

street

streetAddress

timeZone

zipCode