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

faker.location.buildingNumber(): string
faker.location.buildingNumber() // => "5786"
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	boolean \| { ... }	`{}`	Whether to use abbreviated or an options object.
options.useAbbr?	boolean	`false`	If true this will return abbreviated directions (N, E, etc). Otherwise this will return the long name.

Returns: string

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'

Source

View Source

city

Generates a random fictional city name for the locale.

Available since v8.0.0

Returns: string

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

Source

View Source

cityName

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

Available since v8.0.0

Returns: string

faker.location.cityName(): string
faker.location.cityName() // => "Metairie"
faker.location.cityName() // 'San Rafael'
fakerDE.location.cityName() // 'Nürnberg'

Source

View Source

country

Returns a random country name.

Available since v8.0.0

Returns: string

faker.location.country(): string
faker.location.country() // => "Mali"
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' \| { ... }	`{}`	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

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'

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

faker.location.county(): string
faker.location.county() // => "Borders"
fakerEN_GB.location.county() // 'Cambridgeshire'

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	boolean \| { ... }	`{}`	Whether to use abbreviated or an options object.
options.useAbbr?	boolean	`false`	If true this will return abbreviated directions (NW, E, etc). Otherwise this will return the long name.

Returns: string

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'

Source

View Source

latitude

Generates a random latitude.

Available since v8.0.0

Parameters

Name	Type	Default	Description
options	number \| { ... }	`{}`	The upper bound for the latitude or 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.
legacyMin?	number	`-90`	The lower bound for the latitude to generate.
legacyPrecision?	number	`4`	The number of decimal points of precision for the latitude.

Returns: number

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

Source

View Source

longitude

Generates a random longitude.

Available since v8.0.0

Parameters

Name	Type	Default	Description
options?	number \| { ... }	`{}`	The upper bound for the longitude or 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.
legacyMin?	number	`-180`	The lower bound for the longitude to generate.
legacyPrecision?	number	`4`	The number of decimal points of precision for the longitude.

Returns: number

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

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?	[latitude: number, longitude: number] \| { ... }	`{}`	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. If no coordinate is given, a random one will be chosen.
options.radius?	number	`10`	The maximum distance from the given coordinate to the new coordinate.
legacyRadius?	number	`10`	Deprecated, use `options.radius` instead.
legacyIsMetric?	boolean	`false`	Deprecated, use `options.isMetric` instead.

Returns: [latitude: number, longitude: number]

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 ]

Source

View Source

ordinalDirection

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

Available since v8.0.0

Parameters

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

Returns: string

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'

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

faker.location.secondaryAddress(): string
faker.location.secondaryAddress() // => "Suite 578"
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.

Available since v8.0.0

Returns: string

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

Source

View Source

stateAbbr

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

Available since v8.0.0

Returns: string

faker.location.stateAbbr(): string
faker.location.stateAbbr() // => "NV"
faker.location.stateAbbr() // 'ND'

Source

View Source

street

Generates a random localized street name.

Available since v8.0.0

Returns: string

faker.location.street(): string
faker.location.street() // => "Medhurst Rapids"
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

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'

Source

View Source

streetName

Returns a random localized street name.

Available since v8.0.0

Returns: string

faker.location.streetName(): string
faker.location.streetName() // => "b"
fakerDE.location.streetName() // 'Cavill Avenue'

Source

View Source

timeZone

Returns a random time zone.

Available since v8.0.0

Returns: string

faker.location.timeZone(): string
faker.location.timeZone() // => "Asia/Dubai"
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 \| { ... }	`{}`	The format used to generate the the zip code or an options object.
options.format?	string	`faker.definitions.location.postcode`	The optional format used to generate the the zip code.

Returns: string

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

Source

View Source

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

Name	Type	Default	Description
options	string \| { ... }	`{}`	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

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'

Source

View Source

Location ​

Overview ​

buildingNumber ​

Source

cardinalDirection ​

Parameters

Source

city ​

Source

cityName ​

Source

country ​

Source

countryCode ​

Parameters

Source

county ​

Source

direction ​

Parameters

Source

latitude ​

Parameters

Source

longitude ​

Parameters

Source

nearbyGPSCoordinate ​

Parameters

Source

ordinalDirection ​

Parameters

Source

secondaryAddress ​

Source

state ​

Source

stateAbbr ​

Source

street ​

Source

streetAddress ​

Parameters

Source

streetName ​

Source

timeZone ​

Source

zipCode ​

Parameters

See Also

Source

zipCodeByState ​

Parameters

Source

Location

Overview

buildingNumber

cardinalDirection

city

cityName

country

countryCode

county

direction

latitude

longitude

nearbyGPSCoordinate

ordinalDirection

secondaryAddress

state

stateAbbr

street

streetAddress

streetName

timeZone

zipCode

zipCodeByState