Formerly the National Climatic Data Center (NCDC)… more about NCEI »

NCEI Paleo Web Service

This page documents the URL formats and parameters used to get data from the NCEI Paleo web service.

All calls to the web service should be GET requests. Successful requests return a JSON or XML object with two fields: contactInfo which is the same for every request, and study which contains a list of study objects.

Note that when searching via .../paleo-search/, the api call used to retrieve the results is displayed. This can be used to generate examples relevant to your use case.

Examples

The base URL for the web service is located here:
https://www.ncdc.noaa.gov/paleo-search/study/search[.json|.xml]
The return type, JSON or XML, can be specified in the URL. The default is XML.

If you know the id of the study you want, you can provide it as a query parameter: If you don't know exactly which study you want, or you want a collection of studies, you can search the service with the available parameters: Available parameters are documented below. A list of searchable values for several parameters (investigators, locations, keywords, and tree species) can be found here, with an optional dataTypeId parameter: Some parameters can only be used when searching specific data publishers, these are noted next to the parameter name. Arguments to all parameters except searchText must be complete values, e.g. partial names are not permitted. For investigators, locations, keywords, and tree species these values are listed in the params.json file, and multiple values can be searched by joining them with a '|'.

Query parameters

xmlId NOAA NEOTOMA PANGAEA
xmlId=([0-9]+|)[0-9]+
.../paleo-search/study/search.json?xmlId=1840
The id of the original xml document containing the study.
NOAAStudyId NOAA
NOAAStudyId=([0-9]+|)[0-9]+
.../paleo-search/study/search.json?NOAAStudyId=13156
The unique NOAA study id number.
searchText NOAA NEOTOMA PANGAEA
searchText=[a-zA-Z0-9%_-;~]+
.../paleo-search/study/search.json?searchText=younger dryas
.../paleo-search/study/search.json?searchText=loess AND stratigraphy
.../paleo-search/study/search.json?searchText=stratigra%25
.../paleo-search/study/search.json?searchText=f_re
.../paleo-search/study/search.json?searchText=noaa\-tree\-19260
Any text contained in the contents of the study.

This field supports Oracle Text parameters, such as AND, OR, and wildcards (% for multiple characters, _ for single character). Note that some characters (e.g. -, ;, ~) have special meaning in this context. This field cannot contain HTML reserved characters (e.g. <, >, &). Special characters can be searched literally by escaping them with a backslash, as discussed in the Oracle Special Characters documentation.
dataPublisher NOAA NEOTOMA PANGAEA
dataPublisher=[NOAA|NEOTOMA|PANGAEA]
.../paleo-search/study/search.json?dataPublisher=NOAA&dataTypeId=4
The original provider of the study data.
dataTypeId NOAA
dataTypeId=([0-9]{1,2}|)*[0-9]{1,2}
.../paleo-search/study/search.json?dataPublisher=NOAA&dataTypeId=4
Limit the search to only studies of a certain data type, or which contain variables of that data type. Multiple data types can be selected at once like dataTypeId=18|5.

Available data type id's are as follows:
  • 1: BOREHOLE
  • 2: CLIMATE FORCING
  • 3: CLIMATE RECONSTRUCTIONS
  • 4: CORALS AND SCLEROSPONGES
  • 6: HISTORICAL
  • 7: ICE CORES
  • 8: INSECT
  • 9: LAKE LEVELS
  • 10: LOESS
  • 11: PALEOCLIMATIC MODELING
  • 12: FIRE HISTORY
  • 13: PALEOLIMNOLOGY
  • 14: PALEOCEANOGRAPHY
  • 15: PLANT MACROFOSSILS
  • 16: POLLEN
  • 17: SPELEOTHEMS
  • 18: TREE RING
  • 19: OTHER COLLECTIONS
  • 20: INSTRUMENTAL
  • 59: SOFTWARE
  • 60: REPOSITORY
minLat/maxLat NOAA NEOTOMA PANGAEA
minLat=-?[0-9]{1,2}
maxLat=-?[0-9]{1,2}
.../paleo-search/study/search.json?minLat=68&maxLat=69
Valid latitude values are in the range -90 to 90. minLat and maxLat can be used individually or together.
minLon/maxLon NOAA NEOTOMA PANGAEA
minLon=-?[0-9]{1,3}
maxLon=-?[0-9]{1,3}
.../paleo-search/study/search.json?minLon=68&maxLon=69
Valid longitude values are in the range -180 to 180. minLon and maxLon can be used individually or together.
minElev/maxElev NOAA NEOTOMA
minElev=-?[0-9]+
maxElev=-?[0-9]+
.../paleo-search/study/search.json?minElev=100&maxElev=110
Elevation bounds in meters. Elevation can be less than 0. minElev and maxElev can be used individually or together.
earliestYear/latestYear NOAA
earliestYear=-?[0-9]+
latestYear=-?[0-9]+
.../paleo-search/study/search.json?earliestYear=1500&latestYear=0&timeFormat=BP&timeMethod=overEntire&dataTypeId=13
Apply a time bound to the search. These fields should be used in conjunction with timeFormat and timeMethod. earliestYear and latestYear can be used individually or together.
timeFormat NOAA
timeFormat=[CE|BP]
.../paleo-search/study/search.json?earliestYear=1500&latestYear=0&timeFormat=BP&timeMethod=overEntire&dataTypeId=13
Specify the time unit format, either years CE or years BP, to use when searching. Choice of time format will not affect search results (when using properly converted dates) and is provided for convenience only.
timeMethod NOAA
timeMethod=[overAny|entireOver|overEntire]
.../paleo-search/study/search.json?earliestYear=1500&latestYear=0&timeFormat=BP&timeMethod=overEntire&dataTypeId=13
Specify the way in which to apply the time bounds defined by earliestYear and latestYear.
  • overAny: Matches studies where any part of the time coverage lies between the specified min and max
  • entireOver: Matches studies with time coverages that completely bound the specified min and max
  • overEntire: Matches studies with time coverages that are completely bounded by the specified min and max
investigators NOAA NEOTOMA PANGAEA
investigators=([a-zA-Z]+|)*[a-zA-Z]+
.../paleo-search/study/search.json?investigators=Wahl, E.R.
Search for studies containing one or more investigators. The available investigators, grouped by data publisher and data type, can be found in the params.json file.
investigatorsAndOr NOAA NEOTOMA PANGAEA
investigatorsAndOr=[and|or]
.../paleo-search/study/search.json?investigators=Wahl, E.R.|Vose, R.S.&investigatorsAndOr=or
When searching for multiple investigators, specifies whether to find studies containing any of those investigators or all of them. If this field is not supplied the default value is or.
locations NOAA
locations=([a-zA-Z>]+|)*[a-zA-Z>]+
.../paleo-search/study/search.json?locations=Continent>Africa>Eastern Africa>Zambia
Search for studies containing one or more locations. The available locations, grouped by data publisher and data type, can be found in the params.json file.
locationsAndOr NOAA
locationsAndOr=[and|or]
.../paleo-search/study/search.json?locations=Continent>Africa>Eastern Africa>Zambia|Continent>Africa>Eastern Africa>Zimbabwe&locationsAndOr=or
When searching for multiple locations, specifies whether to find studies containing any of those locations or all of them. If this field is not supplied the default value is or.
keywords NOAA
keywords=([a-zA-Z>]+|)*[a-zA-Z>]+
.../paleo-search/study/search.json?keywords=earth science>paleoclimate>paleocean>biomarkers
Search for studies containing one or more keywords. The available keywords, grouped by data publisher and data type, can be found in the params.json file.
keywordsAndOr NOAA
keywordsAndOr=[and|or]
.../paleo-search/study/search.json?keywords=earth science>paleoclimate>paleocean>biomarkers|earth science>paleoclimate>paleocean>lithology&keywordsAndOr=or
When searching for multiple keywords, specifies whether to find studies containing any of those keywords or all of them. If this field is not supplied the default value is or.
species NOAA
species=([a-zA-Z]{4}|)*[a-zA-Z]{4}
.../paleo-search/study/search.json?species=ABAL
Search for studies containing one or more tree species. Species should be indicated by their four letter code. The available species codes, grouped by data publisher and data type, can be found in the params.json file.
speciesAndOr NOAA
speciesAndOr=[and|or]
.../paleo-search/study/search.json?species=ABAL|AGRO&speciesAndOr=or
When searching for multiple species, specifies whether to find studies containing any of those species or all of them. If this field is not supplied the default value is or.
cvWhats NOAA
cvWhats=([a-zA-Z>]+|)*[a-zA-Z>]+
.../paleo-search/study/search.json?cvWhats=chemical composition>compound>inorganic compound>carbon dioxide
Search for studies containing one or more variable 'what' terms. The available whats, grouped by data publisher and data type, can be found in the params.json file.
cvWhatsAndOr NOAA
cvWhatsAndOr=[and|or]
.../paleo-search/study/search.json?cvWhats=chemical composition>compound>inorganic compound>carbon dioxide|chemical composition>compound>organic compound>hydrocarbon>alkane>n-alkane>methane&cvWhatsAndOr=or
When searching for multiple variable whats, specifies whether to find studies containing any of those whats or all of them. If this field is not supplied the default value is or.
cvMaterials NOAA
cvMaterials=([a-zA-Z>]+|)*[a-zA-Z>]+
.../paleo-search/study/search.json?cvMaterials=geological material>identified mineral>carbonate>calcium carbonate>aragonite
Search for studies containing one or more variable materials. The available materials, grouped by data publisher and data type, can be found in the params.json file.
cvMaterialsAndOr NOAA
cvMaterialsAndOr=[and|or]
.../paleo-search/study/search.json?cvMaterials=geological material>identified mineral>carbonate>calcium carbonate>aragonite|biological material>bulk biological material>peat&cvMaterialsAndOr=or
When searching for multiple variable materials, specifies whether to find studies containing any of those materials or all of them. If this field is not supplied the default value is or.
cvSeasonalities NOAA
cvSeasonalities=([a-zA-Z>]+|)*[a-zA-Z>]+
.../paleo-search/study/search.json?cvSeasonalities=annual
Search for studies containing one or more variable seasonalities. The available seasonalities, grouped by data publisher and data type, can be found in the params.json file.
cvSeasonalitiesAndOr NOAA
cvSeasonalitiessAndOr=[and|or]
.../paleo-search/study/search.json?cvSeasonalities=annual|3-month>Aug-Oct&cvSeasonalitiessAndOr=or
When searching for multiple variable seasonalities, specifies whether to find studies containing any of those seasonalities or all of them. If this field is not supplied the default value is or.
reconstructionsOnly NOAA
reconstructionsOnly=[Y|N]
.../paleo-search/study/search.json?headersOnly=true&dataPublisher=NOAA&dataTypeId=4&reconstructionsOnly=Y
Specify whether to return only studies which are, or are not, climate reconstructions. By default both are returned.
headersOnly NOAA NEOTOMA PANGAEA
headersOnly=true
.../paleo-search/study/search.json?species=ABAL&headersOnly=true
Returns only minimal information for each study found , but is much quicker than a full query. If you are performing a search that returns a large number of studies and intend to choose only one from that list to examine in detail, headersOnly may give you enough information to find the xmlId or NOAAStudyId for the study that you actually want.
skip/limit NOAA NEOTOMA PANGAEA
skip=[0-9]+
limit=[0-9]+
.../paleo-search/study/search.json?dataPublisher=NOAA&investigators=Abbott,%20M.B.&limit=10
.../paleo-search/study/search.json?dataPublisher=NOAA&investigators=Abbott,%20M.B.&skip=3
.../paleo-search/study/search.json?dataPublisher=NOAA&investigators=Abbott,%20M.B.&limit=10&skip=3
Retrieves only a specific number of results from a search, and chooses where that number should begin. When doing a broad search that takes too long or returns too much data at once, these options can be used to get the same data in smaller pieces.
recent NOAA
recent=true
.../paleo-search/study/search.json?headersOnly=true&recent=true
.../paleo-search/study/search.json?headersOnly=true&recent=true&limit=50
Changes the order of search results so that recently contributed studies are first. Only studies contributed in the past two years can be found with this option. Because this parameter is designed to be used with very broad searches, by default only the 25 most recent studies are returned. This can be changed with the limit parameter.

Data Bundling

We now offer the ability to package and download data that meets specified criteria via our web service. Note that we do not currently distribute third-party data, such as from Neotoma or Pangaea, but will include links to it in a manifest file when possible. Three new api endpoints are used to support this feature:

/paleo-search/data/search.json?[search params]
.../paleo-search/data/search.json?xmlId=1840
The data search endpoint accepts the same parameters as the study search endpoint, with the exception of headersOnly, skip/limit, and recent. Data bundling operates asynchronously; in response to a /data/search call you will receive a JSON token with confirmation of your request, the parameters being searched, and a job id.
{ "jobId": "2043180573_2017-05-15", "message": "request received", "searchParams": [ "xmlId: 1000099" ] }

/paleo-search/data/status.json?[job id]
.../paleo-search/data/status.json?jobId=2043180573_2017-05-15
Check the status of your data job by polling the /data/status endpoint. The JSON token returned will always have a status field, and will contain other fields depending on the state of the job. If your job is finished, the response will include a link to the data bundle.
{ "status": "working", "message": "packaging data", "percent": "28" }
{ "status": "complete", "archive": "https://www.ncdc.noaa.gov/paleo-data/1099765442_2017-05-15.zip" }

/paleo-search/data/cancel.json?[job id]
.../paleo-search/data/cancel.json?jobId=2043180573_2017-05-15
If you want to cancel a job you can do so with the /data/cancel endpoint.
{ "status": "canceled", "message": "job canceled" }

Several parameters apply only to data bundling requests:

preview NOAA
preview=true
.../paleo-search/study/search.json?preview=true&dataPublisher=NOAA&investigators=Ababneh,%20L.
Returns the list of files that will be included in a bundle request for the given parameters. Be sure to note the 'bundle' field as some studies may be excluded from bundling due to issues such as third-party distribution constraints.
matchLevel NOAA
matchLevel=[study|file]
.../paleo-search/study/search.json?preview=true&matchLevel=file&dataPublisher=NOAA&investigators=Ababneh,%20L.&keywords=earth%20science>paleoclimate>tree-ring>width>more%20info
.../paleo-search/study/search.json?preview=true&matchLevel=study&dataPublisher=NOAA&investigators=Ababneh,%20L.&keywords=earth%20science>paleoclimate>tree-ring>width>more%20info
Specifies how other parameters should be applied when searching for files to bundle:
  • File Match: Only data files which match your search parameters will be included, regardless of matches on other data files in the same study. This is the narrower search option.
  • Study Match: All data files will be included from each selected study where any data file matches your search parameters. This is the broader search option.

Page parameters

Several pages can take query parameters to change their default behavior:

The main search page accepts dataTypeId to specify the default data type to search. The various shuttle boxes will be populated with only values applicable to that data type. This is the same as selecting that data type from the shuttle box on the page. If no dataTypeId is specified, the default is 'all'.
The study page (https://www.ncdc.noaa.gov/paleo-search/study/[NOAAStudyId]) takes the NOAA Study Id for a single study as a URL parameter. If the study contains more than one site, a specific site can be highlighted by providing a siteId.
All reports pages can accept one or more dataTypeId parameters. These pages can also be called with a search param which tells the page to search for the supplied data types as soon as it loads. The location report page can accept reconstruction keywords using reconKeywords, if the Climate Reconstruction data type id specified.