@neaps/tide-database 0.0.20251221 → 0.1.20260107

package/LICENSE

@@ -3,7 +3,8 @@ NOT WITHIN THE "data" DIRECTORY. EACH DATA FILE HAS ITS OWN LICENSE INFORMATION.
 
 The MIT License (MIT)
 
-Copyright (c) 2015 gatsbyjs
+Copyright (c) 2019 Kevin Miller
+Copyright (c) 2025 Brandon Keepers
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -22,4 +23,3 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
-

package/README.md

@@ -1,56 +1,62 @@
-## Tide harmonics database
+# Neaps Tide Database
 
-The availability of good harmonic constituent data varies from country
-to country, resulting in very different tide predeictions depending on
-what products you use. Within the United States, NOAA provides excellent
-harmonic constituents for free, but internationally it is a different
-story.
+> A public database of tide harmonics
 
-We first observed these challenges in Gulfo Nuevo in Argentina. The gulf
-is very deep, with a narrow mouth to the Atlantic and sloping benthic
-profile. As a result, the difference between high and low tides is
-consistently 5 meters or more. Various websites and products we used had
-different levels of accuracy when predicting the tides. We found one
-that was just predicting tides from a station over 200km away, outside
-the gulf, and therefore completely different in terms of water level and
-timing.
+This database includes harmonic constituents for tide prediction from various sources around the world. These constants can be used with a tide harmonic calculator like [Neaps](https://github.com/neaps/neaps) to create astronomical tide predictions.
 
-The various surf or weather report apps either use old data, or base
-large areas of coastline on one station. Many people are still using
-pre-2004 data published in Xtide's Harmbase. Harmbase is great, but it's
-data is locked in binary files and SQL, and the maintainer [has given up on maintaining it outside the US](https://flaterco.com/xtide/faq.html#60)
-.
+## Sources
 
-**All** constituent data is delivered in Meters.
+- ✅ [**NOAA**](https://tidesandcurrents.noaa.gov): National Oceanic and Atmospheric Administration
+  ~3379 stations, mostly in the United States and its territories. Updated monthly via [NOAA's API](https://api.tidesandcurrents.noaa.gov/mdapi/prod/).
 
-Much effort has been made to cover the [requirements from libTCD](https://flaterco.com/xtide/libtcd.html).
+- 🔜 [**TICON-4**](https://www.seanoe.org/data/00980/109129/): TIdal CONstants based on GESLA-4 sea-level records
+  4,838 global stations - ([#16](https://github.com/neaps/tide-database/pull/16))
 
-## Submitting data
+If you know of other public sources of harmonic constituents, please [open an issue](https://github.com/neaps/tide-database/issues/new) to discuss adding them.
 
-If you have **at least a year** of hourly water level observations, you can convert those to harmonic constituents and [submit them to this database online](https://neaps.js.org/harmonics) with a simple form.
+## Usage
 
-Your submission will be automatically converted to a Pull Request to this repository.
+The database is currently only available as an NPM package, but may be available in other formats like [sqlite](https://github.com/neaps/tide-database/issues/18) and [xtide's tcd format](https://github.com/neaps/tide-database/issues/19) in the future.
 
-## Installation
+### JavaScript / TypeScript
 
-```bash
-npm install @neaps/tide-stations
+Install the package:
+
+```sh
+$ npm install @neaps/tide-database
 ```
 
-## Usage
+The package exports an array of all tide stations in the database:
 
 ```typescript
-import { nearest, near, stations } from '@neaps/tide-stations';
+import { constituents, stations } from '@neaps/tide-database';
+
+// Constituents is an array of all harmonic constituents used in the database with a description and speed.
+console.log('Total constituents:', constituents.length);
+console.log(constituents[0]);
 
-// All stations
+// Stations is an array of all the files in `data/`
 console.log('Total stations:', stations.length);
+console.log(stations[0]);
+```
 
-// Find the nearest station to a given lat/lon
-console.log(`Nearest station:`, nearest({ lat: 26.722, lon: -80.031 }));
+## Data Format
 
-// Find the 10 nearest stations to a given lat/lon, in order of distance
-console.log('5 nearest stations:', near({ lat: 26.722, lon: -80.031 }, 10));
-```
+Each tide station is defined in a single JSON file in the [`data/`](./data) directory that includes basic station information, like location and name, and harmonics or subordinate station offsets. The format is defined by the schema in [../schemas/station.schema.json](schemas/station.schema.json), which includes more detailed descriptions of each field. All data is validated against this schema automatically on each change.
+
+## Station Types
+
+Stations can either be _reference_ or _subordinate_, defined in the station's `type` field.
+
+### Reference station
+
+Reference stations have defined harmonic constituents. They should have an array of `harmonic_constituents`. These are usually stations that have a long selection of real water level observations.
+
+### Subordinate station
+
+Subordinate stations are locations that have very similar tides to a reference station. Usually these are geographically close to another reference station.
+
+Subordinate stations have four kinds of offsets, two to correct for water level, and two for the time of high and low tide. They use an `offsets` object to define these items, along with the name of the reference station they are based on.
 
 ## Maintenance
 
@@ -65,7 +71,7 @@ You can also manually trigger the workflow from the Actions tab in GitHub.
 To manually update NOAA stations:
 
 ```bash
-$ tools/update-noaa-stations
+$ tools/update-noaa-stations.ts
 ```
 
 This will scan all existing NOAA station files, fetch any new stations from NOAA's API, and update harmonic constituents for all stations.
@@ -77,3 +83,17 @@ Releases of this database use [Semantic Versioning](https://semver.org/), with t
 * Major version changes indicate breaking changes to the data structure or APIs. However, as long as the version is "0.x", breaking changes may occur without a major version bump.
 * Minor version changes indicate backward-compatible additions to the data structure or APIs, such as new fields.
 * Patch version changes indicate updates to station data, and will always be the current date. For example, "0.1.20260101".
+
+## Releasing
+
+Releases are created by [running the Publish action](https://github.com/neaps/tide-database/actions/workflows/publish.yml) on GitHub Actions. This action will use the major and minor `version` defined in `package.json`, and set the patch version to the current date.
+
+## License
+
+* All code in this repository is licensed under the [MIT License](./LICENSE).
+* The `license` field of each station's JSON file specifies the license for that station.
+* Unless otherwise noted, All other data is licensed under the [Creative Commons Attribution 4.0 International (CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/) license.
+
+If using this project, please attribute it as:
+
+> Tide harmonic constituents from the Neaps tide database (https://github.com/neaps/tide-database)