Tethys Engineering provides curated information on the engineering and economics of marine energy. Use the APIs and downloadable files described below to integrate Tethys Engineering content into other platforms, retrieve records in bulk, or analyze selected results. For automated access, use the APIs rather than scraping website pages.
Tethys Engineering Document API
Tethys Engineering provides a REST API that returns JSON metadata for documents. The API is free and open access and does not have a rate limit. Content refresh is recommended no more frequently than daily, and recurring data pulls are recommended to filter to only newly updated content with URL filters described below.
| Collection | Endpoint |
|---|---|
| Tethys Engineering documents | Documents API |
The API supports integration into large language models like AskPRIMRE, as well information sharing with other databases like the Portal and Repository for Information on Marine Renewable Energy (PRIMRE).
Document Metadata Fields
The document API uses the PRIMRE metadata schema, which is based on internationally accepted schemas like DCAT and Project Open Data and provides shared field definitions for exchanging information across marine energy knowledge hubs.
| Field | Type | Description | Example |
|---|---|---|---|
| uri | Link | Tethys Engineering node URL identifying the document record. | https://tethys-engineering.pnnl.gov/node/656 |
| type | Array | Overarching category to describe the content, with a list that is controlled and managed by PRIMRE. Listed as an array that may contain subcategories. | [ "Document", "Document/Journal Article" ] |
| landingPage | Link | Human-readable URL for the content page on Tethys Engineering. | https://tethys-engineering.pnnl.gov/publications/stream-tidal-energy-potential-puget-sound-washington |
| sourceURL | Link | Link to the external website where the document originated from. | https://journals.sagepub.com/doi/abs/10.1243/09576509JPE748 |
| title | String | Human-readable title of the document. | In-stream tidal energy potential of Puget Sound, Washington |
| description | String | Document abstract or summary. Text may contain HTML entities or encoded characters. | Description of the document. |
| author | Array | Array of individuals who created the document. Authors are always listed as last name first initial ("Last, F."). Some reports do not list individual contributors and an organization is listed instead. | [ "Polagye, B.", "Kawase, M.", "Malte, P." ] |
| organization | Array | Array of company names affiliated with authors or as the sponsor for reports. This array is standardized as the top-level parent organization rather than granular departments. | [ "University of Washington" ] |
| originationDate | Date | The date the document was published. Some journal articles are pre-released, so this date may be in the future. Formatted as YYYY-MM-DD. |
2009-08-01 |
| spatial | Coordinate | The location where research was conducted, if there was a field or lab component to the work. Documents doing analysis or literature reviews may not have a location. Coordinates provided in GeoJSON format, and typically represented as an approximate point. | {"coordinates":["47.714963","-122.465775"],"extent":"point"} |
| technologyType | Array | Array of technology classifications associated with the document. Values are assigned by the Tethys content team. | [ "Current", "Current/Tidal" ] |
| tags | Array | Array of tags such as collection method, resource, engineering, operations, and economics associated with the document. Values are assigned by the Tethys content team. The "Engineering" tag is automatically added to every Tethys document. The full list of tags can be found on the glossary. | [ "Engineering", "Modeling", "Site Characterization" ] |
| modifiedDate | Date | Date and time the Tethys Engineering record was last added or updated in Pacific Time (PT). Formatted as YYYY-MM-DD HH:mm:ss. |
2026-02-03 10:54:27 |
| signatureProject | Array | Special field associated with PRIMRE signature projects, with a list that is controlled and managed by PRIMRE. Learn more about signature projects on PRIMRE. | [ "Reference Model", "RM1: Tidal Current Turbine" ] |
| attachment | Link | Tethys Engineering URL to the attached document, when populated. An empty string indicates no value. | https://tethys-engineering.pnnl.gov/sites/default/files/publications/Keester_2022.pdf |
Document Filtering and Pagination
Add URL parameters to retrieve a subset of records. Begin the first parameter with ? and separate additional parameters with &.
| Parameter | Format | Purpose | Example |
|---|---|---|---|
| modifiedDate | yyyy-mm-dd | Retrieves records last added or updated after the specified date. This refers to the Tethys record’s modification date, not the publication date of the underlying document. | ?modifiedDate=2026-01-01 |
| range | start,length | Retrieves a batch of records, using a zero-based starting position and the requested number of records. Pagination follows the order based on when content was added. | ?range=0,500 |
| type | string | Retrieves a certain type of content as categorized in Tethys. Allowed values are: Document, Summary | ?type=Document |
Examples:
- Records updated after January 1, 2026: https://tethys-engineering.pnnl.gov/api/primre_export?modifiedDate=2026-01-01
- First 500 records: https://tethys-engineering.pnnl.gov/api/primre_export?range=0,500
- Next 500 records: https://tethys-engineering.pnnl.gov/api/primre_export?range=500,500
Tethys Events API
Events do not originate in Tethys Engineering but are imported from the Tethys marine energy events API, as described in the Tethys Developer Documentation page. The Tethys endpoint should be used as the authoritative source of marine energy events, rather than using Tethys Engineering.
Downloads and Citation Exports
Download View or Tool Data
Many views and tools also have simple buttons for downloading filtered results to Excel or CSV, as an option that is more accessible to users. Exports reflect the currently applied search and filter selection. Some of these downloads include additional fields beyond those found in the table. These download options remain hidden unless users are logged in to a free account.
| View or Tool | Format | Download Details |
|---|---|---|
| Knowledge Base | Excel | Maintains selected filters. Additional fields include abstract, external link, and PDF link. |
Share Filtered Results
The Knowledge Base stores search and filter selections in URL parameters. After applying your selections, copy the resulting URL to share that view with colleagues. A shared URL displays matching content available when it is opened. Download the results if you need to preserve a snapshot for analysis.
Export Document Citations
Document pages provide several citation options for referencing publications and importing records into bibliographic management software:
- APA: Copy a formatted citation.
- BibTeX: Export a citation file for compatible reference managers and LaTeX workflows.
- RIS: Export a citation file for compatible bibliographic management tools.
Responsible Automated Access
Tethys Engineering is hosted on Amazon Web Services (AWS) and uses layered firewall rules to manage automated traffic and restrict bot crawling. Pages such as the Knowledge Base and Map Viewer use URL parameters for searching, sorting, and filtering. Following every parameter combination can generate millions of URLs, repeatedly retrieve overlapping content, and place unnecessary demand on the website.
For efficient access:
- Use JSON APIs for programmatic document and event retrieval.
- Use Excel or CSV downloads for selected results and offline analysis.
- Retrieve API records in manageable batches and cache results locally.
- Avoid systematically crawling combinations of search, sort, and filter parameters.
- Contact the Tethys team if the available exports do not meet your integration needs.
Platform, Curation, and Standards
Launched in 2018, Tethys Engineering is built on Drupal 10. Its development follows FAIR and FARR principles to support discoverable, accessible, interoperable, and reusable information, together with AI readiness and reproducibility. All content is verified by human domain experts and organized using established taxonomies to support consistent searching, filtering, and information exchange.
- Technology Types
- Collection Method
- Resource
- Engineering
- Operations
- Economics
The Tethys Engineering website follows U.S. Web Design System (USWDS) standards for design principles, user experience, accessible components, and mobile-friendly layouts. Tethys Engineering adheres to Section 508 accessibility requirements and meets applicable U.S. Department of Energy cybersecurity requirements. Tethys Engineering leverages search engine optimization and actively manages its Google search presence to help users discover relevant information.
Public Access and User Accounts
All Tethys Engineering content is publicly accessible. A free account provides additional features:
- Access to the Tethys Engineering Community networking page
- Connections between a user profile and associated Tethys author pages
- Excel exports of filtered Knowledge Base and tool results
Contact
For API questions, metadata clarification, or assistance with bulk access, contact tethys@pnnl.gov.