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]+
.../paleo-search/study/search.json?xmlId=1840
The id of the original xml document containing the study.
NOAAStudyId NOAA
NOAAStudyId=[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. 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]+|)*[a-zA-Z]+
.../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.
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?species=ABAL&headersOnly=true&recent=true .../paleo-search/study/search.json?species=ABAL&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.

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.