Tethys provides curated information on the environmental effects of wind and marine energy. Use the APIs and downloadable files described below to integrate Tethys content into other platforms, retrieve records in bulk, or analyze selected results. For automated access, use the APIs rather than scraping website pages.
Tethys Document APIs
Tethys provides several REST APIs that returns JSON metadata for documents, summaries, and project sites. These APIs are free and open access and do 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 documents and project sites | Tethys documents API |
| Marine energy documents and project sites | Marine energy documents API |
| Wind energy documents and project sites | Wind energy documents API |
Some content overlaps both marine and wind collections. When combining exports, identify and remove duplicate records. These APIs support integration into large language models like AskPRIMRE and AskWindy, as well information sharing with other databases like the Portal and Repository for Information on Marine Renewable Energy (PRIMRE).
Document Metadata Fields
The document APIs use 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 node URL identifying the document record. | https://tethys.pnnl.gov/node/496570 |
| 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. | https://tethys.pnnl.gov/publications/potential-environmental-effects-marine-renewable-energy-development-state-science |
| sourceURL | Link | Link to the external website where the document originated from. | https://www.mdpi.com/2077-1312/8/11/879 |
| title | String | Human-readable title of the document. | Potential Environmental Effects of Marine Renewable Energy Development—The State of the Science |
| description | String | Content abstract or summary. Text may contain HTML entities or encoded characters. | Description of the document or project site. |
| 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. Project sites list the person who is the point of contact for the information. | [ "Copping, A.", "Hemery, L.", "Garavelli, L.", "Freeman, M.", "Whiting, J.", "Gorton, A.", "Farr, H.", "Rose, D.", "Tugade, L." ] |
| 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. Project sites list the project owner or developer. | [ "Pacific Northwest National Laboratory (PNNL)" ] |
| 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. Project sites list the date when last updated. |
2020-11-04 |
| 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":["36.972554000000","-7.870570000000"],"extent":"point"} |
| technologyType | Array | Array of technology classifications associated with the document or project site. Values are assigned by the Tethys content team. | [ "Current", "Current/Tidal", "Wave" ] |
| tags | Array | Array of tags such as environmental stressor and receptor associated with the document or project site. Values are assigned by the Tethys content team. The "Environment" tag is automatically added to every Tethys document and project site. The full list of tags can be found on the glossary. | [ "Environment", "Collision", "EMF", "Birds", "Fish" ] |
| modifiedDate | Date | Date and time the Tethys 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 URL to the attached document, when populated. An empty string indicates no value. | https://tethys.pnnl.gov/sites/default/files/publications/Copping-et-al-2020-State-of-the-Science.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, Wind Project Site, MRE Project Site | ?type=Document |
Examples:
- Marine energy records updated after January 1, 2026: https://tethys.pnnl.gov/api/primre_export?modifiedDate=2026-01-01
- Wind energy records updated after January 1, 2026: https://tethys.pnnl.gov/api/wind_export?modifiedDate=2026-01-01
- First 500 marine energy records: https://tethys.pnnl.gov/api/primre_export?range=0,500
- Next 500 marine energy records: https://tethys.pnnl.gov/api/primre_export?range=500,500
Tethys Events API
Since events contain different metadata than other content in Tethys, separate REST APIs were created with JSON metadata for events. These APIs are free and open access and do 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 events | Tethys events API |
| Marine energy events | Marine energy events API |
| Wind energy events | Wind energy events API |
Some content overlaps both marine and wind collections. When combining exports, identify and remove duplicate records. This feed supplies the events calendars on both Tethys Engineering and PRIMRE. Use this endpoint to incorporate Tethys marine energy events into another calendar or application.
Event Metadata Fields
Field names are case-sensitive. The following table describes the fields and JSON types shown in the event export sample.
| Field | JSON Type | Description | Example |
|---|---|---|---|
| uri | Link | Tethys node URL identifying the event record. | https://tethys.pnnl.gov/node/2130880 |
| landingPage | Link | Human-readable URL for the event page on Tethys. | https://tethys.pnnl.gov/events/10th-international-sut-osig-conference |
| title | String | Event name. | 10th International SUT OSIG Conference |
| eventType | String | Event category such as Conference, Meeting, Webinar, or Workshop. | Conference |
| description | String | Event summary. Text may contain HTML entities or encoded characters. | Description of the conference and its scope. |
| startDate | Date | Event start date and time in Universal Coordinated Time (UTC), formatted as YYYY-MM-DD HH:mm. |
2027-09-14 08:00 |
| endDate | Date | Event end date and time in Universal Coordinated Time (UTC), formatted as YYYY-MM-DD HH:mm. |
2027-09-16 16:00 |
| location | String | Geographic location of the event, typically represented as City, Country. | London, United Kingdom |
| venue | String | Name of the event venue. | Central Hall Westminster |
| sourceURL | Link | Link to the external event website or source information. | https://sut.org/product/save-the-date-10th-international-sut-osig-conference-geophysics-geoscience-geotechnics-for-energy-and-resource-resilience/ |
| image | Link | TethysURL of an image associated with the event. | https://tethys.pnnl.gov/sites/default/files/events/osig_2027.jpg |
| attachment | Link | Tethys URL to a file attached to the event, such as webinar slides. Only occasionally used, and an empty string indicates no value. | https://tethys.pnnl.gov/sites/default/files/events/SURF-WEC-Webinar-Slides.pdf |
| technologyType | Array | Array of technology classifications associated with the event. Values are assigned by the Tethys content team. | [ "Marine Energy", "Wind Energy" ] |
| signatureProject | Array | Special field associated with PRIMRE signature projects, with a list that is controlled and managed by PRIMRE. | [ "TEAMER" ] |
| modifiedDate | Date | Date and time the Tethys record was last added or updated in Pacific Time (PT). Formatted as YYYY-MM-DD HH:mm:ss. |
2026-02-03 10:54:27 |
| series | String | Indicates whether the event is part of a series or not, as True or False. | False |
| primreEvent | String | Indicates whether the event is hosted by PRIMRE or not, as True or False. | False |
Event 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 |
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. |
| Management Measures Tool for Marine Energy | CSV | Maintains selected filters. |
| Wind Energy Monitoring and Mitigation Technologies Tool | CSV | Maintains selected filters. Fields that are stacked in the online display are separated in the download. |
| Pacific Coast Offshore Wind Environmental Research Project Finder | Excel | Downloads the entire tool. No login required. |
| Pacific Offshore Wind Environmental Research Recommendations | Excel | Downloads the entire tool or synthesized recommendations. No login required. |
| Atlantic Offshore Wind Environmental Research Recommendations | Excel | Downloads the entire tool or synthesized recommendations. No login required. |
Share Filtered Results
The Knowledge Base and many Tethys tools store 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 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 2011, Tethys 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
- Stressors
- Receptors
- Human dimensions
The Tethys website follows U.S. Web Design System (USWDS) standards for design principles, user experience, accessible components, and mobile-friendly layouts. Tethys adheres to Section 508 accessibility requirements and meets applicable U.S. Department of Energy cybersecurity requirements. Tethys leverages search engine optimization and actively manages its Google search presence to help users discover relevant information.
Public Access and User Accounts
Tethys content is publicly accessible, with limited exceptions for restricted working spaces supporting international collaborations such as WREN and OES-Environmental. Access to restricted collaboration spaces requires emailing tethys@pnnl.gov to attain separate authorization.
A free account provides additional features:
- Access to the Tethys Community networking page
- Visibility of point-of-contact email addresses on metadata pages
- 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.