{"id":43529234,"url":"https://github.com/neaps/tide-database","last_synced_at":"2026-02-03T15:37:47.634Z","repository":{"id":35614647,"uuid":"215306198","full_name":"neaps/tide-database","owner":"neaps","description":"A public database of tide harmonics","archived":false,"fork":false,"pushed_at":"2026-01-29T13:10:14.000Z","size":12670,"stargazers_count":8,"open_issues_count":5,"forks_count":3,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-01-30T03:12:39.236Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/neaps.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2019-10-15T13:29:52.000Z","updated_at":"2026-01-29T13:10:27.000Z","dependencies_parsed_at":"2022-08-08T09:31:39.257Z","dependency_job_id":null,"html_url":"https://github.com/neaps/tide-database","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/neaps/tide-database","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neaps%2Ftide-database","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neaps%2Ftide-database/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neaps%2Ftide-database/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neaps%2Ftide-database/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/neaps","download_url":"https://codeload.github.com/neaps/tide-database/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neaps%2Ftide-database/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29048016,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-03T15:19:55.533Z","status":"ssl_error","status_checked_at":"2026-02-03T15:13:09.723Z","response_time":96,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-03T15:37:45.523Z","updated_at":"2026-02-03T15:37:47.620Z","avatar_url":"https://github.com/neaps.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Neaps Tide Database\n\n\u003e A public database of tide harmonics\n\nThis 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.\n\n## Sources\n\n- ✅ [**NOAA**](data/noaa/README.md): National Oceanic and Atmospheric Administration\n  ~3400 stations, mostly in the United States and its territories. Updated monthly via [NOAA's API](https://api.tidesandcurrents.noaa.gov/mdapi/prod/).\n\n- ✅ [**TICON-4**](data/ticon/README.md): TIdal CONstants based on GESLA-4 sea-level records\n  ~4200+ global stations - ([#16](https://github.com/neaps/tide-database/pull/16))\n\nIf 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.\n\n## Usage\n\nThe 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.\n\n### JavaScript / TypeScript\n\nInstall the package:\n\n```sh\n$ npm install @neaps/tide-database\n```\n\nThe package exports an array of all tide stations in the database:\n\n```typescript\nimport { constituents, stations } from \"@neaps/tide-database\";\n\n// Constituents is an array of all harmonic constituents used in the database with a description and speed.\nconsole.log(\"Total constituents:\", constituents.length);\nconsole.log(constituents[0]);\n\n// Stations is an array of all the files in `data/`\nconsole.log(\"Total stations:\", stations.length);\nconsole.log(stations[0]);\n```\n\n#### Searching for stations\n\n##### Geographic search\n\nYou can search for stations by proximity using the `near` and `nearest` functions:\n\n```typescript\nimport { near, nearest } from \"@neaps/tide-database\";\n\n// Find all stations within 10 km of a lat/lon. Returns an array of [station, distanceinKm] tuples.\nconst nearbyStations = near({\n  lon: -122,\n  lat: 37,\n  maxDistance: 10,\n  maxResults: 50,\n});\nconsole.log(\"Nearby stations:\", nearbyStations.length);\n\n// Find the nearest station to a lat/lon\nconst [nearestStation, distance] = nearest({ longitude: -75.5, latitude: 22 });\nconsole.log(\"Nearest station:\", nearestStation.name, \"is\", distance, \"km away\");\n```\n\nBoth functions take the following parameters:\n\n- `latitude` or `lat`: Latitude in decimal degrees.\n- `longitude`, `lon`, or `lng`: Longitude in decimal degrees.\n- `filter`: A function that takes a station and returns `true` to include it in results, or `false` to exclude it.\n- `maxDistance`: Maximum distance in kilometers to search for stations (default: `50` km).\n- `maxResults`: Maximum number of results to return (default: `10`).\n\n##### Full-text search\n\nYou can search for stations by name, region, country, or continent using the `search` function. It supports fuzzy matching and prefix search:\n\n```typescript\nimport { search } from \"@neaps/tide-database\";\n\n// Search for stations by name with fuzzy matching\nconst results = search(\"Boston\");\nconsole.log(\"Found:\", results.length, \"stations\");\nconsole.log(results[0].name);\n\n// Search with a filter function\nconst usStations = search(\"harbor\", {\n  filter: (station) =\u003e station.country === \"United States\",\n  maxResults: 10,\n});\nconsole.log(\"US harbor stations:\", usStations);\n\n// Combine multiple filters\nconst referenceStations = search(\"island\", {\n  filter: (station) =\u003e\n    station.type === \"reference\" \u0026\u0026 station.continent === \"Americas\",\n  maxResults: 20,\n});\nconsole.log(\"Reference stations:\", referenceStations);\n```\n\nThe `search` function takes the following parameters:\n\n- `query` (required): Search string. Supports fuzzy matching and prefix search.\n- `options` (optional):\n  - `filter`: Function that takes a station and returns `true` to include it in results, or `false` to exclude it.\n  - `maxResults`: Maximum number of results to return (default: `20`).\n\n## Data Format\n\nEach 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.\n\n## Station Types\n\nStations can either be _reference_ or _subordinate_, defined in the station's `type` field.\n\n### Reference station\n\nReference 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.\n\n### Subordinate station\n\nSubordinate stations are locations that have very similar tides to a reference station. Usually these are geographically close to another reference station.\n\nSubordinate 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.\n\n## Maintenance\n\nA GitHub Action runs monthly on the 1st of each month to automatically update NOAA tide station data. The workflow:\n\n- Fetches the latest station list and harmonic constituents from NOAA's API\n- Updates existing station files with new data\n- Adds any newly discovered reference stations\n- Creates a pull request if changes are detected\n\nYou can also manually trigger the workflow from the Actions tab in GitHub.\n\nTo manually update NOAA stations:\n\n```bash\n$ tools/update-noaa-stations.ts\n```\n\nThis will scan all existing NOAA station files, fetch any new stations from NOAA's API, and update harmonic constituents for all stations.\n\n## Versioning\n\nReleases of this database use [Semantic Versioning](https://semver.org/), with these added semantics:\n\n- 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.\n- Minor version changes indicate backward-compatible additions to the data structure or APIs, such as new fields.\n- Patch version changes indicate updates to station data, and will always be the current date. For example, \"0.1.20260101\".\n\n## Releasing\n\nReleases 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.\n\n## License\n\n- All code in this repository is licensed under the [MIT License](./LICENSE).\n- The `license` field of each station's JSON file specifies the license for that station.\n- 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.\n\nIf using this project, please attribute it as:\n\n\u003e Tide harmonic constituents from the Neaps tide database (https://github.com/neaps/tide-database)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneaps%2Ftide-database","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fneaps%2Ftide-database","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneaps%2Ftide-database/lists"}