Faker

Appearance

Return to top
On this page

Address

Module to generate addresses and locations.

buildingNumber

Generates a random building number.

Available since v6.2.0

Returns: string

ts
faker.address.buildingNumber(): string
faker.address.buildingNumber() // => "5786"
faker.address.buildingNumber() // '379'

cardinalDirection

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

Available since v5.0.0

Parameters

NameTypeDefaultDescription
useAbbrbooleanfalse

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

Returns: string

ts
faker.address.cardinalDirection(useAbbr: boolean = false): string
faker.address.cardinalDirection() // => "South"
faker.address.cardinalDirection() // 'North'
faker.address.cardinalDirection(false) // 'South'
faker.address.cardinalDirection(true) // 'N'

city

Generates a random localized city name.

Available since v2.0.1

Parameters

NameTypeDefaultDescription
format?number | string

The index of the format to use. Deprecated do not use.

Returns: string

ts
faker.address.city(format?: number | string): string
faker.address.city() // => "Laruecester"
faker.address.city() // 'East Jarretmouth'

cityName

Returns a random localized and existing city name.

Available since v5.5.0

Returns: string

ts
faker.address.cityName(): string
faker.address.cityName() // => "Metairie"
faker.address.cityName() // 'San Rafael'

cityPrefix

Deprecated

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

Returns a random localized city prefix.

Available since v2.0.1

Returns: string

ts
faker.address.cityPrefix(): string
faker.address.cityPrefix() // => "New"
faker.address.cityPrefix() // 'East'

citySuffix

Deprecated

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

Returns a random localized city suffix.

Available since v2.0.1

Returns: string

ts
faker.address.citySuffix(): string
faker.address.citySuffix() // => "stad"
faker.address.citySuffix() // 'mouth'

country

Returns a random country name.

Available since v2.0.1

Returns: string

ts
faker.address.country(): string
faker.address.country() // => "Malta"
faker.address.country() // 'Greece'

countryCode

Returns a random country code.

Available since v3.0.0

Parameters

NameTypeDefaultDescription
alphaCode'alpha-2' | 'alpha-3''alpha-2'

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

Returns: string

ts
faker.address.countryCode(alphaCode: 'alpha-2' | 'alpha-3' = 'alpha-2'): string
faker.address.countryCode() // => "MA"
faker.address.countryCode() // 'SJ'
faker.address.countryCode('alpha-2') // 'GA'
faker.address.countryCode('alpha-3') // 'TJK'

county

Returns a random localized county.

Available since v2.0.1

Returns: string

ts
faker.address.county(): string
faker.address.county() // => "Borders"
faker.address.county() // 'Cambridgeshire'

direction

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

Available since v5.0.0

Parameters

NameTypeDefaultDescription
useAbbrbooleanfalse

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

Returns: string

ts
faker.address.direction(useAbbr: boolean = false): string
faker.address.direction() // => "Northeast"
faker.address.direction() // 'Northeast'
faker.address.direction(false) // 'South'
faker.address.direction(true) // 'NE'

latitude

Generates a random latitude.

Available since v2.0.1

Parameters

NameTypeDefaultDescription
maxnumber90

The upper bound for the latitude to generate.

minnumber-90

The lower bound for the latitude to generate.

precisionnumber4

The number of decimal points of precision for the latitude.

Returns: string

ts
faker.address.latitude(max: number = 90, min: number = -90, precision: number = 4): string
faker.address.latitude() // => "8.7864"
faker.address.latitude() // '-30.9501'
faker.address.latitude(10, -10, 5) // '2.68452'

longitude

Generates a random longitude.

Available since v2.0.1

Parameters

NameTypeDefaultDescription
maxnumber180

The upper bound for the longitude to generate.

minnumber-180

The lower bound for the longitude to generate.

precisionnumber4

The number of decimal points of precision for the longitude.

Returns: string

ts
faker.address.longitude(max: number = 180, min: number = -180, precision: number = 4): string
faker.address.longitude() // => "17.5729"
faker.address.longitude() // '-154.0226'
faker.address.longitude(10, -10, 5) // '-4.03620'

nearbyGPSCoordinate

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

Available since v5.0.0

Parameters

NameTypeDefaultDescription
coordinate?[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.

radiusnumber10

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

isMetricbooleanfalse

If true assume the radius to be in kilometers. If false for miles.

Returns: [latitude: string, longitude: string]

ts
faker.address.nearbyGPSCoordinate(coordinate?: [latitude: number, longitude: number], radius: number = 10, isMetric: boolean = false): [latitude: string, longitude: string]
faker.address.nearbyGPSCoordinate() // => ["8.7864","33.4241"]
faker.address.nearbyGPSCoordinate() // [ '33.8475', '-170.5953' ]
faker.address.nearbyGPSCoordinate([33, -170]) // [ '33.0165', '-170.0636' ]
faker.address.nearbyGPSCoordinate([33, -170], 1000, true) // [ '37.9163', '-179.2408' ]

ordinalDirection

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

Available since v5.0.0

Parameters

NameTypeDefaultDescription
useAbbrbooleanfalse

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

Returns: string

ts
faker.address.ordinalDirection(useAbbr: boolean = false): string
faker.address.ordinalDirection() // => "Southeast"
faker.address.ordinalDirection() // 'Northeast'
faker.address.ordinalDirection(false) // 'Northwest'
faker.address.ordinalDirection(true) // 'NE'

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 v2.0.1

Returns: string

ts
faker.address.secondaryAddress(): string
faker.address.secondaryAddress() // => "Suite 578"
faker.address.secondaryAddress() // 'Apt. 861'

state

Returns a random localized state from this country.

Available since v2.0.1

Returns: string

ts
faker.address.state(): string
faker.address.state() // => "Nevada"
faker.address.state() // 'Georgia'

stateAbbr

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

Available since v2.0.1

Returns: string

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

street

Generates a random localized street name.

Available since v7.0.0

Returns: string

ts
faker.address.street(): string
faker.address.street() // => "Medhurst Rapids"
faker.address.street() // 'Schroeder Isle'

streetAddress

Generates a random localized street address.

Available since v2.0.1

Parameters

NameTypeDefaultDescription
useFullAddressbooleanfalse

When true this will generate a full address. Otherwise it will just generate a street address.

Returns: string

ts
faker.address.streetAddress(useFullAddress: boolean = false): string
faker.address.streetAddress() // => "5786 Little Streets"
faker.address.streetAddress() // '0917 O'Conner Estates'
faker.address.streetAddress(false) // '34830 Erdman Hollow'
faker.address.streetAddress(true) // '3393 Ronny Way Apt. 742'

streetName

Returns a random localized street name.

Available since v2.0.1

Returns: string

ts
faker.address.streetName(): string
faker.address.streetName() // => "Medhurst Rapids"
fakerDE.address.streetName() // 'Cavill Avenue'

streetPrefix

Deprecated

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

Returns a random localized street prefix.

Available since v3.0.0

Returns: string

ts
faker.address.streetPrefix(): string
faker.address.streetPrefix() // => "b"
fakerGH.address.streetPrefix() // 'Boame'

streetSuffix

Deprecated

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

Returns a random localized street suffix.

Available since v2.0.1

Returns: string

ts
faker.address.streetSuffix(): string
faker.address.streetSuffix() // => "Mission"
faker.address.streetSuffix() // 'Streets'

timeZone

Returns a random time zone.

Available since v5.1.0

Returns: string

ts
faker.address.timeZone(): string
faker.address.timeZone() // => "Africa/Harare"
faker.address.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 v2.0.1

Parameters

NameTypeDefaultDescription
format?string

The optional format used to generate the the zip code. By default, a random format is used from the locale zip formats.

Returns: string

ts
faker.address.zipCode(format?: string): string
faker.address.zipCode() // => "57868-5846"
faker.address.zipCode() // '17839'
faker.address.zipCode('####') // '6925'

zipCodeByState

Generates random zip code from state abbreviation. If state abbreviation is not specified, a random zip code is generated according to the locale's zip format. 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 v5.0.0

Parameters

NameTypeDefaultDescription
statestring

The abbreviation of the state to generate the zip code for.

Returns: string

ts
faker.address.zipCodeByState(state: string): string
faker.address.zipCodeByState() // => "57868-5846"
fakerUS.address.zipCodeByState("AK") // '99595'
fakerUS.address.zipCodeByState("??") // '47683-9880'

Released under the MIT License.

Copyright © 2022-present Faker.