Hebcal.com Web APIs allow the developer to specify a location using one of four options.
Location is used to estimate candle-lighting, Havdalah, fast start/end times, and other zmanim (halachic times). All of these times are derived from a solar position calculation, which are approximated from a location (latitude, longitude) and day of year.
Option 1: GeoNames
To specify a location using a GeoNames numeric ID, use the geonameid parameter, e.g. geonameid=3448439
The GeoNames geographical database covers all countries and contains over eleven million placenames that are available for download free of charge. Hebcal.com supports a subset of the full database: approximately 150,000 world cities with a population of 1,000 or more.
For a complete list of IDs that the Hebcal.com web APIs accept, download the cities1000.zip from https://download.geonames.org/export/dump/ and consider only rows with a type of P (inhabited place). Hebcal refreshes this database approximately once per year.
Option 2: United States ZIP code
To specify a location using a 5-digit ZIP code in the US, use the zip parameter, e.g. zip=90210
If a longer ZIP code (for example a ZIP+4) is specified, only the first 5 digits will be considered.
Hebcal licenses a commercial ZIP code database and we refresh this database approximately once per year.
Option 3: Latitude and Longitude
To specify a location using a latitude and longitude and timezone, use 3 required parameters and one optional parameter.
latitude=[-90.0 to 90.0] – latitude in decimal format (e.g.31.76904or-23.5475)longitude=[-180.0 to 180.0] – longitude decimal format (e.g.35.21633or-46.63611)tzid=TimezoneIdentifier. See List of tz database time zones
Be sure to use the “TZ database name” such as America/New_York or Europe/Paris, not a UTC offset.
An optional parameter elev=[1-9000] may also be used to specify the elevation in meters. This parameter will be ignored unless ue=on, see below for further details.
Option 4: Legacy city identifier (deprecated)
To specify a location using one of ~400 Hebcal legacy city identifiers, use the city parameter, e.g. city=GB-London
You must use one of the legacy city identifiers. Case insensitive. This approach is generally deprecated, as we now recommend using geonameid instead.
Elevation
All of the above options can optionally utilize an elevation for sunset calculation. To enable elevation, specify ue=on (default off).
If on, use elevation to affect the calculation of all sunrise/sunset based zmanim. Note: there are some zmanim such as degree-based zmanim that are driven by the amount of light in the sky and are not impacted by elevation. These zmanim intentionally do not support elevation adjustment
Accuracy
For more information on the calculation engine, see How accurate are candle lighting times?