@hebcal/core
    Preparing search index...

    Class Location

    Class representing a geographic location for use with candle-lighting, havdalah, and zmanim calculations.

    Extends GeoLocation from @hebcal/noaa with Jewish-calendar specific data: an Israel/Diaspora flag, ISO country code, and an optional geographic identifier. Also provides Location.lookup for ~60 built-in "classic" Hebcal cities.

    import {Location} from '@hebcal/core';

    // Create a location for a custom address
    const loc = new Location(
      41.85003,    // latitude
      -87.65005,   // longitude
      false,       // not in Israel
      'America/Chicago',
      'Chicago, Illinois, USA',
      'US'
    );

    // Or look up a built-in classic city
    const tlv = Location.lookup('Tel Aviv');

    Hierarchy (View Summary)

    Index

    Constructors

    constructor

    Properties

    admin1? asciiname? elevation geo? latitude locationName longitude population? stateName? timeZoneId zip?

    Methods

    getCountryCode getElevation getGeoId getIsrael getLatitude getLocationName getLongitude getName getShortName getTimeFormatter getTimeZone getTzid setElevation setLatitude setLocationName setLongitude setTimeZone toString addLocation getUsaTzid legacyTzToTzid lookup

    Constructors

    • Initialize a Location instance

      Parameters

      • latitude: number

        Latitude as a decimal, valid range -90 thru +90 (e.g. 41.85003)

      • longitude: number

        Longitude as a decimal, valid range -180 thru +180 (e.g. -87.65005)

      • il: boolean

        in Israel (true) or Diaspora (false)

      • tzid: string

        Olson timezone ID, e.g. "America/Chicago"

      • OptionalcityName: string

        optional descriptive city name

      • OptionalcountryCode: string

        ISO 3166 alpha-2 country code (e.g. "FR")

      • Optionalgeoid: string | number

        optional string or numeric geographic ID

      • Optionalelevation: number

        in meters (default 0)

      Returns Location

    Properties

    admin1?: string
    asciiname?: string
    elevation: number
    geo?: "zip" | "geoname"
    latitude: number
    locationName: string | null
    longitude: number
    population?: number
    stateName?: string
    timeZoneId: string
    zip?: string

    Methods

    • Returns the ISO 3166 alpha-2 country code (e.g. "US", "IL", "FR") passed to the constructor, or undefined if none was provided.

      Returns string | undefined

    • Method to get the elevation in Meters.

      Returns number

      Returns the elevation in Meters.

    • Returns the optional geographic identifier passed to the constructor (typically a GeoNames numeric ID or a US Zip Code string), or undefined if none was provided.

      Returns string | number | undefined

    • Returns true if this location is in Israel (uses the Israeli holiday and Torah-reading schedule), false for the Diaspora.

      Returns boolean

    • Returns number

      Returns the latitude.

    • Returns string | null

      Returns the location name.

    • Returns number

      Returns the longitude.

    • Returns the full descriptive location name passed to the constructor, or null if no name was provided.

      Returns string | null

      Location.lookup('San Francisco')?.getName(); // 'San Francisco, California, USA'

    • Returns the location name truncated at the first comma. Useful for compact display where only the city name is desired.

      Special-cased so that US locations of the form "Washington, DC" or "Washington, D.C., ..." keep the DC / D.C. suffix attached.

      Returns string | null

      Location.lookup('San Francisco')?.getShortName(); // 'San Francisco'
      Location.lookup('Washington DC')?.getShortName(); // 'Washington, DC'

    • Returns a cached 24-hour Intl.DateTimeFormat (e.g. 07:41 or 20:03) configured for this location's timezone. Formatters are memoized by timezone so repeated calls do not allocate.

      Returns DateTimeFormat

      const loc = Location.lookup('Tel Aviv')!;
      const fmt = loc.getTimeFormatter();
      fmt.format(new Date()); // e.g. '18:42'

    • Returns string

      Returns the timeZone.

    • Returns the Olson timezone identifier (e.g. "America/Chicago"). Alias for getTimeZone() from the parent GeoLocation class.

      Returns string

    • Method to set the elevation in Meters above sea level.

      Parameters

      • elevation: number

        The elevation to set in Meters. An Error will be thrown if the value is a negative.

      Returns void

    • Parameters

      • latitude: number

      Returns void

    • Parameters

      • name: string | null

        The setter method for the display name.

      Returns void

    • Parameters

      • longitude: number

      Returns void

    • Method to set the TimeZone.

      Parameters

      • timeZoneId: string

        The timeZone to set.

      Returns void

    • Returns a JSON-serialized representation of this Location. Useful for debugging and structured logging.

      Returns string

    • Registers a new named location with the built-in Location.lookup() registry. Names are stored case-insensitively. Returns false if a location with the same (lower-cased) name is already registered, and true if successfully added.

      Use this to extend the built-in set of ~60 classic Hebcal cities with your own custom locations.

      Parameters

      Returns boolean

      const tlv = new Location(32.0853, 34.7818, true,
        'Asia/Tel_Aviv', 'My Office, Tel Aviv', 'IL');
      Location.addLocation('My Office', tlv);   // true
      Location.lookup('my office')?.getTzid();  // 'Asia/Tel_Aviv'

    • Converts timezone info from Zip-Codes.com to a standard Olson tzid.

      Parameters

      • state: string

        two-letter all-caps US state abbreviation like 'CA'

      • tz: number

        positive number, 5=America/New_York, 8=America/Los_Angeles

      • dst: string

        single char 'Y' or 'N'

      Returns string

      Location.getUsaTzid('AZ', 7, 'Y') // 'America/Denver'

    • Converts a legacy Hebcal-style timezone (a numeric GMT offset plus a coarse DST region) to a standard IANA/Olson timezone ID.

      This exists to migrate data from older Hebcal versions that stored timezones as GMT offset + DST scheme rather than as a full tzid.

      Parameters

      • tz: number

        integer, GMT offset in hours

      • dst: string

        'none', 'eu', 'usa', or 'israel'

      Returns string | undefined

      Location.legacyTzToTzid(2, 'israel'); // 'Asia/Jerusalem'
      Location.legacyTzToTzid(0, 'eu');     // 'Europe/London'
      Location.legacyTzToTzid(0, 'none');   // 'UTC'
      Location.legacyTzToTzid(-5, 'none');  // 'Etc/GMT-5'

    • Creates a location object from one of 60 "classic" Hebcal city names. The following city names are supported: 'Ashdod', 'Atlanta', 'Austin', 'Baghdad', 'Beer Sheva', 'Berlin', 'Baltimore', 'Bogota', 'Boston', 'Budapest', 'Buenos Aires', 'Buffalo', 'Chicago', 'Cincinnati', 'Cleveland', 'Dallas', 'Denver', 'Detroit', 'Eilat', 'Gibraltar', 'Haifa', 'Hawaii', 'Helsinki', 'Houston', 'Jerusalem', 'Johannesburg', 'Kiev', 'La Paz', 'Livingston', 'Las Vegas', 'London', 'Los Angeles', 'Marseilles', 'Miami', 'Minneapolis', 'Melbourne', 'Mexico City', 'Montreal', 'Moscow', 'New York', 'Omaha', 'Ottawa', 'Panama City', 'Paris', 'Pawtucket', 'Petach Tikvah', 'Philadelphia', 'Phoenix', 'Pittsburgh', 'Providence', 'Portland', 'Saint Louis', 'Saint Petersburg', 'San Diego', 'San Francisco', 'Sao Paulo', 'Seattle', 'Sydney', 'Tel Aviv', 'Tiberias', 'Toronto', 'Vancouver', 'White Plains', 'Washington DC', 'Worcester'

      Lookups are case-insensitive. Returns undefined if the name is not recognized. The list can be extended with Location.addLocation.

      Parameters

      • name: string

        case-insensitive classic city name

      Returns Location | undefined

      const loc = Location.lookup('San Francisco');
      console.log(loc?.getTzid()); // 'America/Los_Angeles'

    Settings

    Member Visibility

    On This Page

    Constructors
    Properties
    Methods