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() (or stateAbbr()), 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
faker.location.buildingNumber(): string
faker.location.buildingNumber() // '379'

cardinalDirection ​

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

Available since v8.0.0

Parameters

NameTypeDefaultDescription
options?boolean | { ... }{}

Whether to use abbreviated or an options object. Defaults to{}.

options.abbreviated?booleanfalse

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

Returns: string

ts
faker.location.cardinalDirection(options?: boolean | {
  abbreviated: boolean
} = {}): string
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
faker.location.city(): string
faker.location.city() // 'East Jarretmouth'
fakerDE.location.city() // 'Bad Lilianadorf'

cityName ​

Deprecated

This method is deprecated and will be removed in a future version.

Use faker.location.city() instead.

Returns a random city name from a list of real cities for the locale.

Available since v8.0.0

Returns: string

ts
faker.location.cityName(): string
faker.location.cityName() // 'San Rafael'
fakerDE.location.cityName() // 'Nürnberg'

country ​

Returns a random country name.

Available since v8.0.0

Returns: string

ts
faker.location.country(): string
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
faker.location.countryCode(options: 'alpha-2' | 'alpha-3' | 'numeric' | {
  variant: 'alpha-2' | 'alpha-3' | 'numeric'
} = {}): string
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
faker.location.county(): string
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?boolean | { ... }{}

Whether to use abbreviated or an options object.

options.abbreviated?booleanfalse

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

Returns: string

ts
faker.location.direction(options?: boolean | {
  abbreviated: boolean
} = {}): string
faker.location.direction() // 'Northeast'
faker.location.direction({ abbreviated: true }) // 'SW'

latitude ​

Generates a random latitude.

Available since v8.0.0

Parameters

NameTypeDefaultDescription
optionsnumber | { ... }{}

The upper bound for the latitude or 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.

legacyMin?number-90

The lower bound for the latitude to generate.

legacyPrecision?number4

The number of decimal points of precision for the latitude.

Returns: number

ts
faker.location.latitude(options: number | {
  max: number,
  min: number,
  precision: number
} = {}, legacyMin?: number = -90, legacyPrecision?: number = 4): number
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?number | { ... }{}

The upper bound for the longitude or 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.

legacyMin?number-180

The lower bound for the longitude to generate.

legacyPrecision?number4

The number of decimal points of precision for the longitude.

Returns: number

ts
faker.location.longitude(options?: number | {
  max: number,
  min: number,
  precision: number
} = {}, legacyMin?: number = -180, legacyPrecision?: number = 4): number
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?[latitude: number, longitude: number] | { ... }{}

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.

legacyRadius?number10

Deprecated, use options.radius instead.

legacyIsMetric?booleanfalse

Deprecated, use options.isMetric instead.

Returns: [latitude: number, longitude: number]

ts
faker.location.nearbyGPSCoordinate(options?: [latitude: number, longitude: number] | {
  isMetric: boolean,
  origin: [latitude: number, longitude: number],
  radius: number
} = {}, legacyRadius?: number = 10, legacyIsMetric?: boolean = false): [latitude: number, longitude: number]
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?boolean | { ... }{}

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
faker.location.ordinalDirection(options?: boolean | {
  abbreviated: boolean
} = {}): string
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
faker.location.secondaryAddress(): string
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
faker.location.state(options: {
  abbreviated: boolean
} = {}): string
faker.location.state() // 'Mississippi'
fakerEN_CA.location.state() // 'Saskatchewan'
fakerDE.location.state() // 'Nordrhein-Westfalen'
faker.location.state({ abbreviated: true }) // 'LA'

stateAbbr ​

Deprecated

This method is deprecated and will be removed in a future version.

Use faker.location.state({ abbreviated: true }) instead.

Returns a random localized state's abbreviated name from this country.

Available since v8.0.0

Returns: string

ts
faker.location.stateAbbr(): string
faker.location.stateAbbr() // 'ND'

street ​

Generates a random localized street name.

Available since v8.0.0

Returns: string

ts
faker.location.street(): string
faker.location.street() // 'Schroeder Isle'

streetAddress ​

Generates a random localized street address.

Available since v8.0.0

Parameters

NameTypeDefaultDescription
optionsboolean | { ... }{}

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

ts
faker.location.streetAddress(options: boolean | {
  useFullAddress: boolean
} = {}): string
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'

streetName ​

Deprecated

This method is deprecated and will be removed in a future version.

Use faker.location.street() instead.

Returns a random localized street name.

Available since v8.0.0

Returns: string

ts
faker.location.streetName(): string
fakerDE.location.streetName() // 'Cavill Avenue'

timeZone ​

Returns a random time zone.

Available since v8.0.0

Returns: string

ts
faker.location.timeZone(): string
faker.location.timeZone() // 'Pacific/Guam'

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

NameTypeDefaultDescription
optionsstring | { ... }{}

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

options.format?stringfaker.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

ts
faker.location.zipCode(options: string | {
  format: string,
  state: string
} = {}): string
faker.location.zipCode() // '17839'
faker.location.zipCode('####') // '6925'

zipCodeByState ​

Deprecated

This method is deprecated and will be removed in a future version.

Use faker.location.zipCode({ state }) instead.

Generates random zip code from state abbreviation.

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

Available since v8.0.0

Parameters

NameTypeDefaultDescription
optionsstring | { ... }{}

A state abbreviation or an options object.

options.state?string

The abbreviation of the state to generate the zip code for. If not specified, a random zip code is generated according to the locale's zip format.

Returns: string

ts
faker.location.zipCodeByState(options: string | {
  state: string
} = {}): string
fakerEN_US.location.zipCodeByState("AK") // '99595'
fakerEN_US.location.zipCodeByState() // '47683-9880'
fakerEN_US.location.zipCodeByState({ state: "AK" }) // '99595'

Released under the MIT License.

Copyright © 2022-present Faker.