Skip to content
On this page

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() // => "5786"
faker.location.buildingNumber() // '379'

cardinalDirection

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

Available since v8.0.0

Parameters

NameTypeDefaultDescription
optionsboolean | { ... }{}

Whether to use abbreviated or an options object.

options.useAbbr?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 | {
  useAbbr: boolean
} = {}): string
faker.location.cardinalDirection() // => "South"
faker.location.cardinalDirection() // 'North'
faker.location.cardinalDirection(false) // 'South'
faker.location.cardinalDirection(true) // 'N'
faker.location.cardinalDirection({ useAbbr: true }) // 'W'

city

Generates a random fictional city name for the locale.

Available since v8.0.0

Returns: string

ts
faker.location.city(): string
faker.location.city() // => "Laruecester"
faker.location.city() // 'East Jarretmouth'
fakerDE.location.city() // 'Bad Lilianadorf'

cityName

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() // => "Metairie"
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() // => "Mali"
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' | { ... }{}

The code to return or an options object.

options.variant?'alpha-2' | 'alpha-3''alpha-2'

The code to return. Can be either 'alpha-2' (two letter code) or 'alpha-3' (three letter code).

Returns: string

ts
faker.location.countryCode(options: 'alpha-2' | 'alpha-3' | {
  variant: 'alpha-2' | 'alpha-3'
} = {}): string
faker.location.countryCode() // => "MA"
faker.location.countryCode() // 'SJ'
faker.location.countryCode('alpha-2') // 'GA'
faker.location.countryCode('alpha-3') // 'TJK'

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
faker.location.county() // => "Borders"
fakerEN_GB.location.county() // 'Cambridgeshire'

direction

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

Available since v8.0.0

Parameters

NameTypeDefaultDescription
optionsboolean | { ... }{}

Whether to use abbreviated or an options object.

options.useAbbr?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 | {
  useAbbr: boolean
} = {}): string
faker.location.direction() // => "Northeast"
faker.location.direction() // 'Northeast'
faker.location.direction(false) // 'South'
faker.location.direction(true) // 'NE'
faker.location.direction({ useAbbr: 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() // => 8.7864
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
faker.location.latitude(10) // 5.7225
faker.location.latitude(10, -10) // -9.6273
faker.location.latitude(10, -10, 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() // => 17.5729
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. If no coordinate is given, a random one will be chosen.

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() // => [8.7864,33.4241]
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
optionsboolean | { ... }{}

Whether to use abbreviated or an options object.

options.useAbbr?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 | {
  useAbbr: boolean
} = {}): string
faker.location.ordinalDirection() // => "Southeast"
faker.location.ordinalDirection() // 'Northeast'
faker.location.ordinalDirection(false) // 'Northwest'
faker.location.ordinalDirection(true) // 'NE'
faker.location.ordinalDirection({ useAbbr: 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() // => "Suite 578"
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.

Available since v8.0.0

Returns: string

ts
faker.location.state(): string
faker.location.state() // => "Nevada"
faker.location.state() // 'Mississippi'
fakerEN_CA.location.state() // 'Saskatchewan'
fakerDE.location.state() // 'Nordrhein-Westfalen'

stateAbbr

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() // => "NV"
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() // => "Medhurst Rapids"
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() // => "5786 Little Streets"
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

Returns a random localized street name.

Available since v8.0.0

Returns: string

ts
faker.location.streetName(): string
faker.location.streetName() // => "b"
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() // => "Asia/Dubai"
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 the zip code or an options object.

options.format?stringfaker.definitions.location.postcode

The optional format used to generate the the zip code.

Returns: string

ts
faker.location.zipCode(options: string | {
  format: string
} = {}): string
faker.location.zipCode() // => "57868-5846"
faker.location.zipCode() // '17839'
faker.location.zipCode('####') // '6925'

zipCodeByState

Generates random zip code from state abbreviation.

Only works for locales with postcode_by_state definition. If a locale does not have a postcode_by_state definition, a random zip code is generated according to the locale's zip format.

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
faker.location.zipCodeByState() // => "57868-5846"
fakerEN_US.location.zipCodeByState("AK") // '99595'
fakerEN_US.location.zipCodeByState("??") // '47683-9880'

Released under the MIT License.