@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 the 65 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
    constructor
    admin1? asciiname? elevation geo? latitude locationName longitude population? stateName? timeZoneId zip?
    getAntimeridianAdjustment getCountryCode getElevation getGeoId getIsrael getLatitude getLocalMeanTimeOffset getLocationName getLongitude getName getShortName getTimeFormatter getTimeZone getTzid setElevation setLatitude setLocationName setLongitude setTimeZone toString addLocation getUsaTzid legacyTzToTzid lookup

    • 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

    admin1?: string

    First-level administrative division (e.g. a US state or a French region) as an abbreviation, such as "CA". Not set by this package; populated by callers that hydrate a Location from a geo database.

    asciiname?: string

    City name in plain ASCII, for sorting or URL generation. Not set by this package.

    elevation: number
    geo?: "zip" | "geoname"

    Which kind of lookup produced this location: 'zip' for a US Zip Code or 'geoname' for a GeoNames city. Not set by this package.

    latitude: number
    locationName: string | null
    longitude: number
    population?: number

    Approximate population of the city. Not set by this package.

    stateName?: string

    Full name of the first-level administrative division, such as "California". Not set by this package.

    timeZoneId: string
    zip?: string

    US Zip Code, such as "02912". Not set by this package.

    • Adjust the date for antimeridian crossover. This is needed to deal with edge cases such as Samoa that use a different calendar date than expected based on their geographic location.

      The actual Time Zone offset may deviate from the expected offset based on the longitude. Since the 'absolute time' calculations are always based on longitudinal offset from UTC for a given date, the date is presumed to only increase East of the Prime Meridian, and to only decrease West of it. For Time Zones that cross the antimeridian, the date will be artificially adjusted before calculation to conform with this presumption.

      For example, Apia, Samoa with a longitude of -171.75 uses a local offset of +14:00. When calculating sunrise for 2018-02-03, the calculator should operate using 2018-02-02 since the expected zone is -11. After determining the UTC time, the local DST offset of UTC+14:00 should be applied to bring the date back to 2018-02-03.

      Parameters

      • date: PlainDate

        the date, at the start of which (in this location's time zone) the offset is read

      Returns number

      the number of days to adjust the date This will typically be 0 unless the date crosses the antimeridian

    • 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.

    • A method that will return the location's local mean time offset in milliseconds from local standard time. The globe is split into 360°, with 15° per hour of the day. For a local that is at a longitude that is evenly divisible by 15 (longitude % 15 == 0), at solar noon (with adjustment for the equation of time) the sun should be directly overhead, so a user who is 1° west of this will have noon at 4 minutes after standard time noon, and conversely, a user who is 1° east of the 15° longitude will have noon at 11:56 AM.

      Parameters

      • instant: Instant

        the instant at which to read the time zone offset (DST is taken into account)

      Returns number

      the offset in milliseconds not accounting for Daylight saving time. A positive value will be returned East of the 15° timezone line, and a negative value West of it.

    • 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.

      Note that the built-in classic cities are named by city alone, so getName() and getShortName return the same string for them.

      Returns string | null

      const loc = new Location(41.85003, -87.65005, false,
        'America/Chicago', 'Chicago, Illinois, USA', 'US');
      loc.getName(); // 'Chicago, Illinois, USA'
      Location.lookup('San Francisco')?.getName(); // 'San Francisco'

    • 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

      const chi = new Location(41.85003, -87.65005, false,
        'America/Chicago', 'Chicago, Illinois, USA', 'US');
      chi.getShortName(); // 'Chicago'
      const dc = new Location(38.89511, -77.03637, false,
        'America/New_York', 'Washington, D.C., USA', 'US');
      dc.getShortName(); // 'Washington, D.C.'

    • 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 65 classic Hebcal cities with your own custom locations.

      Parameters

      • cityName: string

        name to register the location under (case insensitive)

      • location: Location

        the Location instance to register

      Returns boolean

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

    • 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 65 "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