{"id":38676495,"url":"https://github.com/internetofwater/nldi-services","last_synced_at":"2026-05-19T00:09:41.442Z","repository":{"id":37468006,"uuid":"52825896","full_name":"internetofwater/nldi-services","owner":"internetofwater","description":"Network Linked Data Index Navigation Web Services","archived":false,"fork":false,"pushed_at":"2026-03-26T19:39:51.000Z","size":2728,"stargazers_count":21,"open_issues_count":33,"forks_count":13,"subscribers_count":4,"default_branch":"master","last_synced_at":"2026-03-27T08:21:19.072Z","etag":null,"topics":["acwi","nhdplus","nldi","usgs-waterdata-labs","water"],"latest_commit_sha":null,"homepage":"https://waterdata.usgs.gov/blog/nldi-intro/","language":"Dockerfile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"cc0-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/internetofwater.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","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":"2016-02-29T21:25:34.000Z","updated_at":"2026-03-26T19:38:48.000Z","dependencies_parsed_at":"2023-09-24T12:10:50.759Z","dependency_job_id":"e4bb24b0-3bba-4e90-b1b9-1dd92538b0e6","html_url":"https://github.com/internetofwater/nldi-services","commit_stats":{"total_commits":498,"total_committers":24,"mean_commits":20.75,"dds":0.6726907630522088,"last_synced_commit":"bb05c690c9c699f1513d289d273841a0181d2027"},"previous_names":[],"tags_count":45,"template":false,"template_full_name":null,"purl":"pkg:github/internetofwater/nldi-services","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/internetofwater%2Fnldi-services","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/internetofwater%2Fnldi-services/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/internetofwater%2Fnldi-services/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/internetofwater%2Fnldi-services/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/internetofwater","download_url":"https://codeload.github.com/internetofwater/nldi-services/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/internetofwater%2Fnldi-services/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31307484,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5: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":["acwi","nhdplus","nldi","usgs-waterdata-labs","water"],"created_at":"2026-01-17T10:01:05.974Z","updated_at":"2026-04-02T14:05:16.185Z","avatar_url":"https://github.com/internetofwater.png","language":"Dockerfile","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Network Linked Data Index Services\n\n[![Spotless Check](https://github.com/internetofwater/nldi-services/actions/workflows/spotless.yml/badge.svg)](https://github.com/internetofwater/nldi-services/actions/workflows/spotless.yml)\n[![codecov](https://codecov.io/gh/internetofwater/nldi-services/branch/master/graph/badge.svg)](https://codecov.io/gh/internetofwater/nldi-services)\n\nThis repository houses code behind the Network Linked Data Index (NLDI) API [(Swagger Docs)](https://api.water.usgs.gov/nldi/swagger-ui/index.html).\n\n## Table of Contents\n\n- [Network Linked Data Index Services](#network-linked-data-index-services)\n  - [Table of Contents](#table-of-contents)\n  - [Public API](#public-api)\n    - [Top Level Path](#top-level-path)\n    - [Up/Down Stream Navigation](#updown-stream-navigation)\n    - [Up/Down Stream Data](#updown-stream-data)\n    - [Query Parameters](#query-parameters)\n    - [Other Endpoints](#other-endpoints)\n  - [Development](#development)\n    - [Dependencies](#dependencies)\n    - [Docker Compose](#docker-compose)\n    - [Environment Variables](#environment-variables)\n    - [Testing](#testing)\n    - [Pipelines](#pipelines)\n      - [Test](#test)\n      - [Build](#build)\n      - [Deploy](#deploy)\n\n## Public API\n\nThe services are accessed via an HTTP GET request. All output is generated as JSON and GeoJSON.\n\n### Top Level Path\n\nThe root path for the NLDI services is `/api/nldi` and follows the hostname under which it is hosted. For example, the QA public endpoint is \u003chttps://labs-beta.waterdata.usgs.gov/api/nldi/\u003e and the production endpoint is \u003chttps://api.water.usgs.gov/nldi/\u003e. The root path will not return any information. Instead, utilize the sub-paths mentioned in the [Swagger documention](https://api.water.usgs.gov/nldi/swagger-ui/index.html) or the examples below.\n\nThe [/api/nldi/linked-data](https://api.water.usgs.gov/nldi/linked-data/) endpoint will give you the valid data source names for the other endpoints. There is also a health check at `/about/health` and version information at `/about/info`.\n\nIn general, the API uses hypermedia to help discover options from a given endpoint. A summary of these options follows.\n\n### Up/Down Stream Navigation\n\n/{featureSource}/{featureSourceId}/navigation/{navigationMode} where:\n\n- `{featureSource}` identifies the source used to start navigation:\n  - The `comid` `{featureSource}` starts the navigation from an NHDPlus comid\n  - any of the network linked feature sources (listed at /)\n- `{featureSourceId}` the NHDPlus comid or feature from which to start the navigation\n- `{navigationMode}` is the direction and type of navigation:\n  - `DD` is `D`ownstream navigation with `D`iversions\n  - `DM` is `D`ownstream navigation on the `M`ain channel\n  - `PP` is `P`oint to `P`oint navigation (the `stopComid` query parameter is required and must be downstream of the `{comid}`)\n  - `UM` is `U`pstream navigation on the `M`ain channel\n  - `UT` is `U`pstream navigation including all `T`ributaries\n\n### Up/Down Stream Data\n\n/{featureSource}/{featureSourceId}/navigation/{navigationMode}/{dataSource} where:\n\n- `{featureSource}` identifies the source used to start navigation\n- `{featureSourceId}` the NHDPlus comid or other feature from which to start the navigation\n- `{navigationMode}` is the direction and type of navigation\n- `{dataSource}` is the abbreviation of the data source to return\n\n### Query Parameters\n\nNavigations accept query parameters to further refine/restrict the navigation being requested.\n\n- `f=json` if an html media type is requested explicitely, a blank html page is returned. `f=json` will override this html accept header.\n- `distance={dist}` **REQUIRED** limits the navigation to `{dist}` kilometers from the starting point\n- `stopComid={stopid}` for use with `PP` navigation between the `{featureSourceId}` and `{stopid}`\n  - (only applicable to NHDPlus comid navigation and the `{stopid}` must be downstream of the `{featureSourceId}`)\n\n### Other Endpoints\n\nThe NLDI includes additional helper endpoints that will be documented here at a later date. See the [Swagger documentation](https://api.water.usgs.gov/nldi/swagger-ui/index.html) and [NLDI intro page](https://waterdata.usgs.gov/blog/nldi-intro/) for more.\n\n## Development\n\nThis is a Spring Batch/Boot project.  All of the normal caveats relating to a Spring Batch/Boot application apply.\nIn general, do not run this project via Docker locally, since it places everything under root ownership.\nRather, start up the demo db and create an application.yml file as described below, then run the project from your IDE.\n\n### Dependencies\n\nThis application utilizes a PostgreSQL database.\n[nldi-db](https://github.com/internetofwater/nldi-db) contains everything you need to set up a development database environment. It includes data for the Yahara River in Wisconsin.\n\n### Docker Compose\n\nThis project includes a Docker-Compose file with all necessary variables predefined.\nFirst, start the demo database by running:\n\n```shell\ndocker-compose up -d nldi-db\n```\n\nThen, build and start the NLDI services by running:\n\n```shell\ndocker-compose up nldi-services\n```\n\nThese test services will be accessible at \u003clocalhost:8080/nldi\u003e. \\\nIf you would like to build these images using a mirror url simply set a `DOCKER_MIRROR` environment variable or include\nit as a build argument.\n\nSee the [nldi-db project](https://github.com/internetofwater/nldi-db) for instructions to use different configurations of the database.\n\n### Environment Variables\n\nTo run the project (connecting to a separately running db instance) you will need to create the file application.yml in the project's root directory and add the following (normal defaults are filled in):\n\n```yaml\nnldiDbHost: localhost\nnldiDbPort: 5437 #Or whatever port you map it to\nnldiDbUsername: dbUserName #See nldi-db project .env file 'NLDI_READ_ONLY_USERNAME'\nnldiDbPassword: dbPassword #See nldi-db project .env file 'NLDI_READ_ONLY_PASSWORD'\nnldiDbName: dbName #See nldi-db project .env file 'NLDI_DATABASE_NAME'\nnldiProtocol: http\nnldiHost: owi-test.usgs.gov:8080\nnldiPath: /test-url\npygeoapiUrl: https://labs-beta.waterdata.usgs.gov/api/nldi/pygeoapi/\n\nserverContextPath: /nldi\nspringFrameworkLogLevel: INFO\nserverPort: 8080\n\nspring.security.user.password: changeMe\n```\n\n### Testing\n\nThis project contains JUnit tests. Maven can be used to run them (in addition to the capabilities of your IDE).\n\nTo run the unit tests of the application use:\n\n```shell\nmvn test\n```\n\nTo additionally start up a Docker database and run the integration tests of the application use:\n\n```shell\nmvn verify\n```\n\n### Pipelines\n\nThis project has automated pipelines for test, build, and deploy.\n\n#### Test\n\nThe test pipeline is run when a pull request is created and consists of two parts. The first step is linting using the Spotless Maven plugin. This validates that any code changes fit within certain style guidelines to maintain readability and consistency. The second stage runs all unit and integration tests. If both of these stages pass, a pull request is eligible to be merged.\n\n#### Build\n\nThe build pipeline happens internally to the USGS and are triggered manually. The `docker build` command is run to construct a Docker container after which it is pushed to an internal container registry.\n\n#### Deploy\n\nSimilar to the build pipeline, deploys are internal and triggered manually. The infrastructure components are managed with this pipeline and retrieve the Docker container from the previously mentioned container registry..\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finternetofwater%2Fnldi-services","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finternetofwater%2Fnldi-services","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finternetofwater%2Fnldi-services/lists"}