Introduction
The NODE API provides programmatic access to marine genomic data. This documentation will help you understand how to use the API to query and retrieve data from the NODE platform.
Overview
NODE provides a RESTful API allows you to access all available data in the database through HTTP requests. The API has several endpoints and parameters, allowing you to parse through our data with flexible queries.
You can use this API to query the entire database for projects, samples, analyses, features, and taxonomic information for integration into your own applications, data analysis workflows, or visualizations.
The API is public and requires no authentication or API keys to use. GET requests are the only type supported.
Quick Start
import requests
import json
import pandas as pd
# Make API request to desired endpoint
url = "https://www.oceandnaexplorer.org//api/project"
response = requests.get(url)
# Check if request was successful
if response.status_code == 200:
# Parse JSON response and print it
data = response.json()
results = data['result']
print("JSON Response:")
print(json.dumps(results, indent=2))
# Convert to DataFrame and print it
df = pd.DataFrame(results)
print("--------------------")
print("DataFrame:")
print(df)
else:
print(f"Error: {response.status_code}")
if response.content:
print(f"Error message: {response.json()['error']}")
library(httr)
library(jsonlite)
# Make API request
url <- "https://www.oceandnaexplorer.org//api/project"
response <- GET(url)
# Check if request was successful
if (http_status(response)$category == "Success") {
# Parse JSON response
data <- content(response, "text") %>% fromJSON()
results <- data$result
print(results)
} else {
print(paste("Error:", http_status(response)$reason))
if (length(content(response)) > 0) {
print(paste("Error message:", content(response)$error))
}
}
Database Schema
This section shows the relationships between tables in the database, and what fields are available for each table. This will help you effectively query relations and filter by fields.
Entity Relationship Diagram
The following diagram shows the relationships between tables in the database:
Use this diagram as a reference when constructing queries with the relations parameter.
Table Definitions
The dropdown menus below show the fields available for each table in NODE. You can use this information in your API requests to query and filter on specific fields.
Field | Type | Optional | Options |
---|---|---|---|
id | integer | ||
project_id | string | ||
userId | string | ||
dateSubmitted | date | ||
editHistory | json | ||
recordedBy | string | ||
recordedByID | string | true | |
project_contact | string | ||
institution | string | true | |
institutionID | string | true | |
project_name | string | ||
study_factor | string | true | |
detection_type | string | ||
neg_cont_0_1 | boolean | true | 0 | 1 | false | true | not applicable: control sample | not applicable: sample group | not applicable | missing: not collected: synthetic construct | missing: not collected: lab stock | missing: not collected: third party data | missing: not collected | missing: not provided: data agreement established pre-2023 | missing: not provided | missing: restricted access: endangered species | missing: restricted access: human-identifiable | missing: restricted access |
parent_project_id | string | true | |
pos_cont_0_1 | boolean | true | 0 | 1 | false | true | not applicable: control sample | not applicable: sample group | not applicable | missing: not collected: synthetic construct | missing: not collected: lab stock | missing: not collected: third party data | missing: not collected | missing: not provided: data agreement established pre-2023 | missing: not provided | missing: restricted access: endangered species | missing: restricted access: human-identifiable | missing: restricted access |
license | string | true | |
rightsHolder | string | true | |
accessRights | string | true | |
informationWithheld | string | true | |
dataGeneralizations | string | true | |
bibliographicCitation | string | true | |
associated_resource | string | true | |
mod_date | date | true | |
checkls_ver | string | ||
seq_archive | string | true | |
code_repo | string | true | |
biological_rep | integer | true |
Field | Type | Optional | Options |
---|---|---|---|
id | integer | ||
samp_name | string | ||
project_id | string | ||
samp_category | string | ||
decimalLatitude | float | true | |
decimalLongitude | float | true | |
verbatimLatitude | string | true | |
verbatimLongitude | string | true | |
verbatimCoordinateSystem | string | true | |
verbatimSRS | string | true | |
geo_loc_name | string | ||
eventDate | string | ||
eventDurationValue | float | true | |
eventDurationUnit | string | true | |
verbatimEventDate | string | true | |
verbatimEventTime | string | true | |
verbatimDateEnd | string | true | |
verbatimTimeEnd | string | true | |
env_broad_scale | string | true | |
env_local_scale | string | true | |
env_medium | string | true | |
habitat_natural_artificial_0_1 | boolean | true | 0 | 1 | false | true | not applicable: control sample | not applicable: sample group | not applicable | missing: not collected: synthetic construct | missing: not collected: lab stock | missing: not collected: third party data | missing: not collected | missing: not provided: data agreement established pre-2023 | missing: not provided | missing: restricted access: endangered species | missing: restricted access: human-identifiable | missing: restricted access |
samp_collect_method | string | true | |
samp_collect_device | string | true | |
samp_size | float | true | |
samp_size_unit | string | true | |
samp_store_temp | float | true | |
samp_store_sol | string | true | |
samp_store_dur | string | true | |
samp_store_method_additional | string | true | |
dna_store_loc | string | true | |
samp_store_loc | string | true | |
samp_mat_process | string | true | |
filter_passive_active_0_1 | boolean | true | 0 | 1 | false | true | not applicable: control sample | not applicable: sample group | not applicable | missing: not collected: synthetic construct | missing: not collected: lab stock | missing: not collected: third party data | missing: not collected | missing: not provided: data agreement established pre-2023 | missing: not provided | missing: restricted access: endangered species | missing: restricted access: human-identifiable | missing: restricted access |
filter_onsite_dur | string | true | |
size_frac_low | float | true | |
size_frac | float | true | |
filter_diameter | float | true | |
filter_surface_area | float | true | |
filter_material | string | true | |
filter_name | string | true | |
precip_chem_prep | string | true | |
precip_force_prep | float | true | |
precip_time_prep | float | true | |
precip_temp_prep | float | true | |
prepped_samp_store_temp | float | true | |
prepped_samp_store_sol | string | true | |
prepped_samp_store_dur | float | true | |
prep_method_additional | string | true | |
prefilter_material | string | true | |
pump_flow_rate | float | true | |
pump_flow_rate_unit | string | true | |
stationed_sample_dur | string | true | |
sample_derived_from | string | true | |
sample_composed_of | string | true | |
biological_rep_relation | string | true | |
samp_vol_we_dna_ext | float | true | |
samp_vol_we_dna_ext_unit | string | true | |
nucl_acid_ext_lysis | string | true | |
nucl_acid_ext_sep | string | true | |
nucl_acid_ext | string | true | |
nucl_acid_ext_kit | string | true | |
nucl_acid_ext_modify | string | true | |
dna_cleanup_0_1 | boolean | true | 0 | 1 | false | true | not applicable: control sample | not applicable: sample group | not applicable | missing: not collected: synthetic construct | missing: not collected: lab stock | missing: not collected: third party data | missing: not collected | missing: not provided: data agreement established pre-2023 | missing: not provided | missing: restricted access: endangered species | missing: restricted access: human-identifiable | missing: restricted access |
dna_cleanup_method | string | true | |
concentration | float | true | |
concentration_method | string | true | |
ratioOfAbsorbance260_280 | float | true | |
pool_dna_num | integer | true | |
nucl_acid_ext_method_additional | string | true | |
concentration_unit | string | true | |
date_ext | string | true | |
samp_weather | string | true | |
minimumDepthInMeters | float | true | |
maximumDepthInMeters | float | true | |
tot_depth_water_col | float | true | |
elev | float | true | |
temp | float | true | |
chlorophyll | float | true | |
light_intensity | float | true | |
misc_param | float | true | |
ph | float | true | |
ph_meth | string | true | |
salinity | float | true | |
suspend_part_matter | float | true | |
tidal_stage | string | true | |
turbidity | float | true | |
water_current | float | true | |
solar_irradiance | string | true | |
wind_direction | string | true | |
wind_speed | float | true | |
diss_inorg_carb | float | true | |
diss_inorg_nitro | float | true | |
diss_org_carb | float | true | |
diss_org_nitro | float | true | |
diss_oxygen | float | true | |
tot_diss_nitro | float | true | |
tot_inorg_nitro | float | true | |
tot_nitro | float | true | |
tot_part_carb | float | true | |
tot_org_carb | float | true | |
tot_org_c_meth | float | true | |
tot_nitro_content | float | true | |
tot_nitro_cont_meth | float | true | |
tot_carb | float | true | |
part_org_carb | float | true | |
part_org_nitro | float | true | |
nitrate | float | true | |
nitrite | float | true | |
nitro | float | true | |
org_carb | float | true | |
org_matter | float | true | |
org_nitro | float | true | |
diss_inorg_carb_unit | string | true | |
diss_inorg_nitro_unit | string | true | |
diss_org_carb_unit | string | true | |
diss_org_nitro_unit | string | true | |
diss_oxygen_unit | string | true | |
nitrate_unit | string | true | |
nitrite_unit | string | true | |
nitro_unit | string | true | |
org_carb_unit | string | true | |
org_matter_unit | string | true | |
org_nitro_unit | string | true | |
part_org_carb_unit | string | true | |
part_org_nitro_unit | string | true | |
tot_carb_unit | string | true | |
tot_diss_nitro_unit | string | true | |
tot_inorg_nitro_unit | string | true | |
tot_nitro_content_unit | string | true | |
tot_nitro_unit | string | true | |
tot_org_carb_unit | string | true | |
tot_part_carb_unit | string | true | |
rel_cont_id | string | true |
Field | Type | Optional | Options |
---|---|---|---|
id | integer | ||
assay_name | string | ||
neg_cont_type | string | true | |
pos_cont_type | string | true | |
sterilise_method | string | true | |
pcr_0_1 | boolean | 0 | 1 | false | true | not applicable: control sample | not applicable: sample group | not applicable | missing: not collected: synthetic construct | missing: not collected: lab stock | missing: not collected: third party data | missing: not collected | missing: not provided: data agreement established pre-2023 | missing: not provided | missing: restricted access: endangered species | missing: restricted access: human-identifiable | missing: restricted access | |
thermocycler | string | true | |
amplificationReactionVolume | float | true | |
assay_validation | string | true | |
targetTaxonomicAssay | string | true | |
targetTaxonomicScope | string | true | |
target_gene | string | ||
target_subfragment | string | true | |
ampliconSize | float | true | |
pcr_primer_forward | string | true | |
pcr_primer_reverse | string | true | |
pcr_primer_name_forward | string | true | |
pcr_primer_name_reverse | string | true | |
pcr_primer_reference_forward | string | true | |
pcr_primer_reference_reverse | string | true | |
pcr_primer_vol_forward | float | true | |
pcr_primer_vol_reverse | float | true | |
pcr_primer_conc_forward | float | true | |
pcr_primer_conc_reverse | float | true | |
probeReporter | string | true | |
probeQuencher | string | true | |
probe_seq | string | true | |
probe_ref | string | true | |
probe_conc | float | true | |
commercial_mm | string | true | |
custom_mm | string | true | |
pcr_dna_vol | float | true | |
pcr_rep | integer | true | |
nucl_acid_amp | string | true | |
pcr_cond | string | true | |
annealingTemp | string | true | |
pcr_cycles | float | true | |
pcr_analysis_software | string | true | |
pcr_method_additional | string | true | |
assay_type | string |
Field | Type | Optional | Options |
---|---|---|---|
id | integer | ||
lib_id | string | ||
assay_name | string | ||
samp_name | string | ||
barcoding_pcr_appr | string | true | |
platform | string | true | |
instrument | string | true | |
seq_kit | string | true | |
lib_layout | string | true | |
sequencing_location | string | true | |
adapter_forward | string | true | |
adapter_reverse | string | true | |
lib_screen | string | true | |
seq_method_additional | string | true | |
mid_forward | string | true | |
mid_reverse | string | true | |
filename | string | true | |
filename2 | string | true | |
seq_run_id | string | true | |
biosample_accession | string | true | |
input_read_count | integer | true | |
checksum_filename | string | true | |
checksum_filename2 | string | true | |
lib_conc | float | true | |
lib_conc_meth | string | true | |
lib_conc_unit | string | true | |
phix_perc | float | true | |
checksum_method | string | true | |
pcr2_amplificationReactionVolume | float | true | |
pcr2_analysis_software | string | true | |
pcr2_annealingTemp | float | true | |
pcr2_commercial_mm | string | true | |
pcr2_cond | string | true | |
pcr2_custom_mm | string | true | |
pcr2_cycles | integer | true | |
pcr2_dna_vol | float | true | |
pcr2_method_additional | string | true | |
pcr2_plate_id | string | true | |
pcr2_thermocycler | string | true | |
pcr_plate_id | string | true | |
block_ref | string | true | |
block_seq | string | true | |
block_taxa | string | true | |
inhibition_check | string | true | |
inhibition_check_0_1 | boolean | true | 0 | 1 | false | true | not applicable: control sample | not applicable: sample group | not applicable | missing: not collected: synthetic construct | missing: not collected: lab stock | missing: not collected: third party data | missing: not collected | missing: not provided: data agreement established pre-2023 | missing: not provided | missing: restricted access: endangered species | missing: restricted access: human-identifiable | missing: restricted access |
Field | Type | Optional | Options |
---|---|---|---|
id | integer | ||
analysis_run_name | string | ||
userId | string | ||
dateSubmitted | date | ||
editHistory | json | ||
project_id | string | ||
assay_name | string | ||
sop_bioinformatics | string | true | |
trim_method | string | true | |
trim_param | string | true | |
demux_tool | string | true | |
demux_max_mismatch | integer | true | |
merge_tool | string | true | |
merge_min_overlap | integer | true | |
min_len_cutoff | integer | true | |
min_len_tool | string | true | |
error_rate_tool | string | true | |
error_rate_type | string | true | |
error_rate_cutoff | float | true | |
chimera_check_method | string | true | |
chimera_check_param | string | true | |
otu_clust_tool | string | true | |
otu_clust_cutoff | float | true | |
min_reads_cutoff | float | true | |
min_reads_cutoff_unit | string | true | |
min_reads_tool | string | true | |
otu_db | string | true | |
otu_db_custom | string | true | |
tax_assign_cat | string | true | |
otu_seq_comp_appr | string | true | |
tax_class_id_cutoff | float | true | |
tax_class_query_cutoff | float | true | |
tax_class_collapse | string | true | |
tax_class_other | string | true | |
screen_contam_method | string | true | |
screen_geograph_method | string | true | |
screen_nontarget_method | string | true | |
screen_other | string | true | |
bioinfo_method_additional | string | true | |
asv_method | string | true | |
dada2_trunc_len_f | integer | true | |
dada2pe_trunc_len_r | integer | true | |
dada2_trim_left_f | integer | true | |
dada2pe_trim_left_r | integer | true | |
dada2_max_ee_f | integer | true | |
dada2pe_max_ee_r | integer | true | |
dada2_trunc_q | integer | true | |
dada2_pooling_method | string | true | |
dada2_chimera_method | string | true | |
dada2_min_fold_parent_over_abundance | integer | true | |
dada2_n_reads_learn | integer | true | |
deblur_trim_length | integer | true | |
deblur_sample_stats | boolean | true | 0 | 1 | false | true | not applicable: control sample | not applicable: sample group | not applicable | missing: not collected: synthetic construct | missing: not collected: lab stock | missing: not collected: third party data | missing: not collected | missing: not provided: data agreement established pre-2023 | missing: not provided | missing: restricted access: endangered species | missing: restricted access: human-identifiable | missing: restricted access |
deblur_mean_error | float | true | |
deblur_indel_prob | float | true | |
deblur_indel_max | integer | true | |
deblur_min_reads | integer | true | |
deblur_min_size | integer | true | |
repseq_min_length | integer | true | |
repseq_max_length | integer | true | |
repseq_min_abundance | float | true | |
repseq_min_prevalence | float | true | |
discard_untrimmed | boolean | true | 0 | 1 | false | true | not applicable: control sample | not applicable: sample group | not applicable | missing: not collected: synthetic construct | missing: not collected: lab stock | missing: not collected: third party data | missing: not collected | missing: not provided: data agreement established pre-2023 | missing: not provided | missing: restricted access: endangered species | missing: restricted access: human-identifiable | missing: restricted access |
otu_num_tax_assigned | integer | true | |
output_otu_num | integer | true | |
output_read_count | integer | true | |
otu_final_description | string | true | |
otu_raw_description | string | true |
Field | Type | Optional | Options |
---|---|---|---|
id | integer | ||
samp_name | string | ||
analysis_run_name | string | ||
featureid | string | ||
organismQuantity | integer |
Field | Type | Optional | Options |
---|---|---|---|
id | integer | ||
featureid | string | ||
dna_sequence | string | ||
sequenceLength | integer |
Field | Type | Optional | Options |
---|---|---|---|
id | integer | ||
analysis_run_name | string | ||
featureid | string | ||
taxonomy | string | ||
Confidence | float |
Field | Type | Optional | Options |
---|---|---|---|
id | integer | ||
taxonomy | string | ||
verbatimIdentification | string | ||
domain | string | true | |
kingdom | string | true | |
supergroup | string | true | |
division | string | true | |
subdivision | string | true | |
phylum | string | true | |
class | string | true | |
order | string | true | |
family | string | true | |
genus | string | true | |
species | string | true |
Query Construction Guide
This section explains how to construct API queries to retrieve data from the NODE database.
URL Structure
API requests follow this general pattern:
Where:
- [endpoint] is the name of the API endpoint
- [parameters] are optional query parameters
Query Parameter Syntax
Query parameters follow this format: parameter=value
For example, to select specific fields:
Multiple Parameters
Combine multiple parameters using an ampersand:
Example URLs
Here are some example URLs to help you understand query construction:
Basic query:
With relations:
With filtering:
These examples demonstrate different ways to query the API. You can adjust them to suit your specific needs.
API Endpoints
This section documents all available API endpoints and their functionality.
Get All Tables
Returns a list of all available tables in the database. Use this to discover what data is available through the API.
{
"message": "Success",
"result": [
"project",
"sample",
"assay",
"library",
"analysis",
"occurrence",
"feature",
"assignment",
"taxonomy"
]
}
Get Table Fields
{
"message": "Success",
"result": [{
"id": 1,
"project_id": "noaa-aoml-gomecc4",
"userId": "user_2de7fXfAmCCpbB6yr6PbK0Esc9f",
"dateSubmitted": "2025-03-03T16:26:52.455Z",
"recordedBy": "Luke Thompson",
"recordedByID": "https://orcid.org/0000-0002-3911-1280",
"project_contact": "Luke Thompson",
"institution": "NOAA/AOML",
"institutionID": "https://www.aoml.noaa.gov/omics",
"project_name": "eDNA from Gulf of Mexico Ecosystems and Carbon Cruise 2021 (GOMECC-4)",
"study_factor": "water column spatial series",
"detection_type": "multi taxon detection",
"license": "http://creativecommons.org/publicdomain/zero/1.0/legalcode",
"rightsHolder": "US Government",
"accessRights": "no rights reserved",
"informationWithheld": "no information withheld",
"dataGeneralizations": "no data generalizations",
"bibliographicCitation": "https://doi.org/10.1101/2024.07.30.605667",
"associated_resource": "http://www.earthmicrobiome.org/",
"mod_date": "2024-10-31T04:00:00.000Z",
"checkls_ver": "1.1",
"seq_archive": "PRJNA887898",
"code_repo": "https://github.com/aomlomics/gomecc",
"expedition_id": "GOMECC-4 (2021)"
}]
}
Query Table Data
Returns multiple records from a specific table. This endpoint supports various query parameters for filtering, selecting fields, including relations, and limiting results.
{
"message": "Success",
"result": [
{ "id": 1, "project_name": "eDNA from Gulf of Mexico Ecosystems and Carbon Cruise 2021 (GOMECC-4)" }
]
}
Get Single Record
{
"message": "Success",
"result": {
"id": 22,
"taxonomy": "Eukaryota;Obazoa;Opisthokonta;Metazoa;Arthropoda;Crustacea;Maxillopoda;Centropages;Centropages_furcatus;",
"verbatimIdentification": "Eukaryota;Obazoa;Opisthokonta;Metazoa;Arthropoda;Crustacea;Maxillopoda;Centropages;Centropages_furcatus;",
"domain": null,
"kingdom": "Eukaryota",
"supergroup": "Obazoa",
"division": "Opisthokonta",
"subdivision": "Metazoa",
"phylum": null,
"class": "Arthropoda",
"order": "Crustacea",
"family": "Maxillopoda",
"genus": "Centropages",
"species": "Centropages furcatus"
}
}
Query Parameters
Query parameters allow you to customize your API requests. This section details all available parameters and how to use them.
Field Selection
Specifies which fields to include in the response. When omitted, all fields are returned.
This example returns only the id
, project_name
, and dateSubmitted
fields for each project.
Field Filtering
Filters results to return only records where the specified field contains the provided value.
This example returns all projects where the project_name
field contains "Test".
Relations
Includes related data from other tables in the response. The relation names can be lowercase or capitalized and must be plural, separated by commas.
This example returns all projects along with their related samples and analyses. By default, only the ID field is included for related records.
Relation Field Options
Controls whether to include only the ID field on relations (default), or to include all fields.
This example returns all projects along with all fields from their related samples, not just the sample IDs.
ID Filtering
Filters results to return only records with the specified IDs. IDs must be numbers greater than 0, separated by commas.
This example returns only projects with IDs 1, 2, and 3.
Result Limiting
Limits the number of results returned. Must be a positive number.
This example limits the results to 20 projects.
Complete Examples
This section provides complete example queries to help you understand how to combine various parameters.
Basic Query
This simple query returns just the ID and name of all projects.
{
"message": "Success",
"result": [
{ "id": 1, "project_name": "Gulf of Mexico Metabarcoding" },
{ "id": 2, "project_name": "Atlantic Coastal eDNA Survey" }
]
}
With Relations
Example URL: /api/project?relations=samples&relationsAllFields=true
This query returns all projects along with complete information about their related samples.
Example Response:
{
"message": "Success",
"result": [
{
"id": 1,
"project_name": "Gulf of Mexico Metabarcoding",
"description": "Metabarcoding study of the Gulf of Mexico",
"samples": [
{
"id": 1,
"sample_id": "GOM-001",
"collection_date": "2022-05-15",
"location": "Gulf of Mexico"
},
{
"id": 2,
"sample_id": "GOM-002",
"collection_date": "2022-05-16",
"location": "Gulf of Mexico"
}
]
}
]
}
With Filtering
Example URL: /api/project?project_name=Test&institution=University
This query returns projects where the project_name contains "Test" AND the institution contains "University".
Example Response:
{
"message": "Success",
"result": [
{
"id": 10,
"project_name": "Test Project",
"description": "A test project",
"institution": "University of Marine Science"
}
]
}
Combined Parameters
Example URL: /api/project?fields=id,project_name&relations=samples&limit=5
This query combines field selection, relations, and a result limit.
Example Response:
{
"message": "Success",
"result": [
{
"id": 1,
"project_name": "Gulf of Mexico Metabarcoding",
"samples": [
{ "id": 1 },
{ "id": 2 }
]
},
{
"id": 2,
"project_name": "Atlantic Coastal eDNA Survey",
"samples": [
{ "id": 3 },
{ "id": 4 }
]
}
]
}
Single Record
Example URL: /api/project/5?fields=id,project_name&relations=samples
This query retrieves a single project by ID, with selected fields and related samples.
Example Response:
{
"message": "Success",
"result": {
"id": 5,
"project_name": "Caribbean Coral Microbiome Study",
"samples": [
{ "id": 15 },
{ "id": 16 },
{ "id": 17 }
]
}
}
Response Format
This section explains the structure of API responses so you can properly parse and use the returned data.
Success Structure
Successful API responses have a consistent structure:
The message
field will always contain "Success" for successful requests.
The result
field will contain either:
- An array of objects (for multiple results)
- A single object (for single record requests)
[Additional response format details coming soon]
Error Structure
Error responses follow this structure:
The message
field will always contain "Error" when something goes wrong.
The error
field contains a human-readable description of the error.
[Additional error response details coming soon]
FAQ
Frequently asked questions about using the NODE API.
Q: Do I need an API key to use the NODE API?
A: No, the NODE API is currently open and does not require authentication or API keys.
Q: Are there rate limits for API usage?
A: While there are no strict rate limits currently in place, we ask that you be considerate with your API usage. For applications requiring high-volume requests, please contact us.
Q: I'm not familiar with APIs. How do I get started?
A: An API (Application Programming Interface) allows computers to talk to each other. To use our API, you'll need to make HTTP requests to our endpoints. The simplest way to start is by pasting one of our example URLs into your browser's address bar to see the raw JSON response. For more advanced usage, you can use programming languages like Python, R, or JavaScript.
Q: How do I report issues with the API?
A: Please submit any API issues through our GitHub repository's issue tracker.
Q: How do I cite data obtained through the API?
A: Please cite the NODE platform and the specific projects from which you obtained data. Each project has citation information available through the web interface.