Faker

Appearance

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

ts
function buildingNumber(): string;

Examples

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

cardinalDirection ​

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

Available since v8.0.0

Parameters

NameTypeDefaultDescription
options{ ... }{}

The options to use.

options.abbreviated?booleanfalse

If true this will return abbreviated directions (N, E, etc). Otherwise this will return the long name.

Returns: string

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

Examples

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

city ​

Generates a random localized city name.

Available since v8.0.0

Returns: string

ts
function city(): string;

Examples

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

continent ​

Returns a random continent name.

Available since v9.1.0

Returns: string

ts
function continent(): string;

Examples

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

country ​

Returns a random country name.

Available since v8.0.0

Returns: string

ts
function country(): string;

Examples

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

countryCode ​

Returns a random ISO_3166-1 country code.

Available since v8.0.0

Parameters

NameTypeDefaultDescription
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

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

Examples

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

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

ts
function county(): string;

Examples

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

direction ​

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

Available since v8.0.0

Parameters

NameTypeDefaultDescription
options{ ... }{}

The options to use.

options.abbreviated?booleanfalse

If true this will return abbreviated directions (NW, E, etc). Otherwise this will return the long name.

Returns: string

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

Examples

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

language ​

Returns a random spoken language.

Available since v9.4.0

Returns: Language

ts
function language(): Language;

Examples

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

latitude ​

Generates a random latitude.

Available since v8.0.0

Parameters

NameTypeDefaultDescription
options{ ... }{}

An options object.

options.max?number90

The upper bound for the latitude to generate.

options.min?number-90

The lower bound for the latitude to generate.

options.precision?number4

The number of decimal points of precision for the latitude.

Returns: number

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

Examples

ts
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

longitude ​

Generates a random longitude.

Available since v8.0.0

Parameters

NameTypeDefaultDescription
options{ ... }{}

An options object.

options.max?number180

The upper bound for the longitude to generate.

options.min?number-180

The lower bound for the longitude to generate.

options.precision?number4

The number of decimal points of precision for the longitude.

Returns: number

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

Examples

ts
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

nearbyGPSCoordinate ​

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

Available since v8.0.0

Parameters

NameTypeDefaultDescription
options{ ... }{}

The options for generating a GPS coordinate.

options.isMetric?booleanfalse

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?number10

The maximum distance from the given coordinate to the new coordinate.

Returns: [latitude: number, longitude: number]

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

Examples

ts
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 ]

ordinalDirection ​

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

Available since v8.0.0

Parameters

NameTypeDefaultDescription
options{ ... }{}

Whether to use abbreviated or an options object.

options.abbreviated?booleanfalse

If true this will return abbreviated directions (NW, SE, etc). Otherwise this will return the long name.

Returns: string

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

Examples

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

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

ts
function secondaryAddress(): string;

Examples

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

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

NameTypeDefaultDescription
options{ ... }{}

An options object.

options.abbreviated?booleanfalse

If true this will return abbreviated first-level administrative entity names. Otherwise this will return the long name.

Returns: string

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

Examples

ts
faker.location.state() // 'Mississippi'
fakerEN_CA.location.state() // 'Saskatchewan'
fakerDE.location.state() // '