ERDDAP > REST 风格的 Web 服务

访问 ERDDAP 的 RESTful Web 服务

ERDDAP具有以下特点：

Web 应用程序 – 具有可供浏览器用户使用的表单的网页（在本例中，用于获取数据、图表或有关数据集的信息）。
RESTful Web 服务 – 计算机程序可以使用的 URL（在本例中，用于获取数据、图表和有关数据集的信息）。

对于每个带有表单的ERDDAP网页（供您作为使用浏览器的人使用），都有一个相应的ERDDAP Web 服务，该服务旨在方便计算机程序和脚本使用。例如，人类可以使用此 URL 对有趣的数据集进行全文搜索：
https://coastwatch.pfeg.noaa.gov/erddap/zh-CN/search/index.html?page=1&itemsPerPage=1000&searchFor=temperature
通过将 URL 中的文件扩展名从 .html 更改为.json （或 .csv、 .htmlTable 、 .jsonlCSV1 、 .xhtml等）：
https://coastwatch.pfeg.noaa.gov/erddap/zh-CN/search/index.json?page=1&itemsPerPage=1000&searchFor=temperature
我们得到一个 URL，计算机程序或Java Script 脚本可以使用它来以更适合计算机程序的格式（如JSON （外部链接）

获取相同的信息。

在ERDDAP之上构建事物

ERDDAP中有许多功能可供您编写的计算机程序或脚本使用。您可以使用它们在ERDDAP之上构建其他 Web 应用程序或 Web 服务，让ERDDAP完成大部分工作！因此，如果您有更好的ERDDAP数据接口或需要轻松访问数据的网页的想法，我们鼓励您构建自己的 Web 应用程序、Web 服务或网页并使用ERDDAP作为基础。您的系统可以从ERD的ERDDAP或其他ERDDAP安装中获取数据、图表和其他信息，或者您可以建立您自己的ERDDAP服务器，可以公开访问或仅供私人访问。

RESTful URL 请求

ERDDAP对用户界面信息（例如搜索结果）的请求使用 Web 的通用请求标准：通过HTTP GET （外部链接）

发送的 URL &externalLinkHtml;。这与您在网页上填写表单并单击Submit时浏览器使用的机制相同。要使用HTTP GET ，您需要生成一个特殊格式的 URL（可能包含查询）并使用HTTP GET发送。您可以手动生成这些 URL 并将其输入到浏览器的地址文本字段中（例如，
https://coastwatch.pfeg.noaa.gov/erddap/zh-CN/search/index.json?page=1&itemsPerPage=1000&searchFor=temperature ）
或者，您可以编写计算机程序或网页脚本来创建 URL、发送它并获取响应。之所以选择通过HTTP GET URL，是因为

它们使用起来非常简单。
它们工作得很好。
它们受到普遍支持（在浏览器、计算机语言、操作系统工具等）。
它们是表述性状态转移 (REST ) 和面向资源架构 (ROA ) 的基础。
它们有助于将万维网用作大型分布式应用程序，例如通过mashups AJAX应用程序
它们是无状态的就像ERDDAP一样，这使得系统更简单。
URL 完整地定义了给定的请求，因此您可以在浏览器中为其添加书签、将其写在笔记中、通过电子邮件发送给朋友等。

百分比编码

在 URL 中，有些字符是不允许的（例如空格），而其他字符则具有特殊含义（例如，查询中的“&”用于分隔键=值对）。当您在网页上填写表单并点击提交时，您的浏览器会自动对 URL 中的特殊字符进行百分比编码（外部链接）

（例如，空格变为 %20），例如，
https://coastwatch.pfeg.noaa.gov/erddap/zh-CN/search/index.html?page=1&itemsPerPage=1000&searchFor=temperature%20wind%20speed
但是如果您的计算机程序或脚本生成 URL，则它可能需要自己进行百分比编码。如果是这样，那么查询值中除 A-Za-z0-9_-!.~'()* 之外的所有字符（ '='符号后面的部分）可能需要编码为 %HH，其中 HH 是字符的 2 位十六进制值，例如，空格变为 %20。 #127 以上的字符必须转换为 UTF-8 字节，然后每个 UTF-8 字节都必须进行百分比编码（向程序员寻求帮助）。编程语言具有执行此操作的工具（例如，参见Java的java.net.URLEncoder （外部链接）

和Java Script 的encodeURIComponent() （外部链接）

），并且有些网站可以为您进行百分比编码/解码（外部链接）

响应文件类型

尽管使用浏览器的人希望以 HTML 文档的ERDDAP接收用户界面结果（例如搜索结果），但计算机程序通常更喜欢以简单、易于解析、不太冗长的文档形式获取结果。ERDDAP 可以将用户界面结果作为数据表返回，这些文件类型常见且对计算机程序友好：

.csv - 以逗号分隔的 ASCII 文本表。（更多信息)
.htmlTable - 包含表格数据的 .html 网页。（更多信息)
.itx - 一个 Igor 文本文件，每列数据都有一个波形。（更多信息)
.json - 类似表格的 JSON 文件。（更多信息或ERDDAP特定信息)
.jsonlCSV1 - 一个“优于 CSV”的 JSON 行文件，第一行包含列名。（更多信息)
.jsonlCSV - 一个“优于 CSV”的 JSON 行文件，没有列名。（更多信息)
.jsonlKVP - 带有 Key:Value 对的 JSON 行文件。（更多信息)
.mat - MATLAB 二进制文件。（更多信息)
.nc - 一个扁平的、表格状的NetCDF -3 二进制文件。（更多信息)
.nccsv - 一个平面的、表格状的、类似NetCDF的 ASCII CSV 文件。（更多信息)
.tsv - 制表符分隔的 ASCII 文本表。（更多信息)
.xhtml - 包含表格数据的 XHTML (XML) 文件。（更多信息)

在每个结果表格式中（除了.jsonlKVP ，其中列名在每一行上）：

每列都有一个列名和一种信息类型。
表格的第一行是列名。
后续行包含您请求的信息。

这些纯文件类型中的内容也与 .html 响应略有不同——它故意被设计得非常简洁，以便计算机程序更容易使用。

响应的一致数据结构
本页描述的所有用户界面服务都可以返回上面列出的任何常见文件格式的数据表。希望您可以编写一个过程来解析其中一种格式的数据表。然后您可以重复使用该过程来解析来自任何这些服务的响应。这应该会使处理ERDDAP变得更容易。

.csv和.tsv详细信息

如果 .csv 文件中的数据具有内部双引号或逗号， ERDDAP将严格遵循 .csv 规范：它会在数据周围加上双引号，并将内部双引号加倍。
.csv 或.tsv文件中的特殊字符的编码类似于JSON 反斜杠编码字符：\n（换行符）、\\（反斜杠）、\f（换页符）、\t（制表符）、\r（回车符）或 \u hhhh语法。

jsonp
通过在查询末尾添加“& .json p= functionName ”，现在.json文件的请求可以包含可选的jsonp （外部链接）请求。基本上，这会告诉ERDDAP在响应的开头添加“ functionName (” 并在响应的末尾添加“)”。 functionName的第一个字符必须是 ISO 8859 字母或“_”。每个可选的后续字符必须是 ISO 8859 字母、“_”、数字或“。”。如果最初没有查询，请在查询中省略“&”。

griddap 和tabledap提供不同的文件类型
上面列出的文件类型是ERDDAP可用于响应用户界面类型的请求（例如，搜索请求）的文件类型ERDDAP支持一组不同的文件类型用于科学数据（例如，卫星和浮标数据）请求（请参阅griddap和tabledap文档）。

请求压缩文件

ERDDAP不提供存储在压缩文件（例如.zip或.gzip ）中的结果。相反， ERDDAP会在客户端发送的HTTP GET请求标头中查找accept-encoding （外部链接）

如果在 accept-encoding 列表中找到了受支持的压缩类型（ gzip 、 x-gzip或deflate ）， ERDDAP会在 HTTP 响应标头中包含“content‑encoding”，并在传输数据时对其进行压缩。客户端程序负责查找content-encoding并相应地解压缩数据。请求压缩是可选的，但压缩响应通常要快 3-10 倍，因此如果您要下载大量大文件，这将节省大量时间。（请注意，请求压缩的 .png 文件没有任何好处，因为文件的内容已经压缩。）

默认情况下，浏览器和OPeNDAP客户端总是请求压缩数据并解压返回的数据。
使用curl时，在命令行中添加--compressed以告诉curl请求压缩响应并自动解压缩。
对于其他客户端软件，您已明确设置了这一点。
这是一个Java示例。
这是一个Python示例（尽管您应该处理deflate的响应或者不请求deflate ）。

ERDDAP服务的访问 URL

ERDDAP具有以下计算机程序的 URL 访问点：

要获取主要资源访问 URL列表，请使用
.csv, .htmlTable, .itx, .json, .jsonlCSV1, .jsonlCSV, .jsonlKVP, .mat, .nc, .nccsv, .tsv, or .xhtml.
要获取所有数据集的当前列表，请使用
.csv, .htmlTable, .itx, .json, .jsonlCSV1, .jsonlCSV, .jsonlKVP, .mat, .nc, .nccsv, .tsv, or .xhtml.
要获取特定数据集的元数据（变量及其属性的列表），使用
https://coastwatch.pfeg.noaa.gov/erddap/zh-CN /info/ datasetID /index .fileType
例如，
.csv, .htmlTable, .itx, .json, .jsonlCSV1, .jsonlCSV, .jsonlKVP, .mat, .nc, .nccsv, .tsv, or .xhtml.
要获取数据集的全文搜索结果（以"searchFor=wind%20speed"为例），请使用
.csv, .htmlTable, .itx, .json, .jsonlCSV1, .jsonlCSV, .jsonlKVP, .mat, .nc, .nccsv, .tsv, or .xhtml.
（您的程序或脚本可能需要对查询中的值进行百分比编码 ;。）

或者，使用OpenSearch 1.1标准对数据集进行全文搜索。
要获取数据集高级搜索结果（以"searchFor=wind%20speed"为例），请使用
.csv, .htmlTable, .itx, .json, .jsonlCSV1, .jsonlCSV, .jsonlKVP, .mat, .nc, .nccsv, .tsv, or .xhtml.
但是，请在浏览器中尝试使用高级搜索来找出所有可选参数。（您的程序或脚本可能需要对查询中的值进行百分比编码 ;。）
要获取categoryAttributes列表（例如，institution、 long_name 、standard_name），请使用
.csv, .htmlTable, .itx, .json, .jsonlCSV1, .jsonlCSV, .jsonlKVP, .mat, .nc, .nccsv, .tsv, or .xhtml.
要获取特定 categoryAttribute 的类别列表（以“standard_name”为例），请使用
.csv, .htmlTable, .itx, .json, .jsonlCSV1, .jsonlCSV, .jsonlKVP, .mat, .nc, .nccsv, .tsv, or .xhtml.
要获取特定类别的数据集列表（以“standard_name=time”为例），请使用
.csv, .htmlTable, .itx, .json, .jsonlCSV1, .jsonlCSV, .jsonlKVP, .mat, .nc, .nccsv, .tsv, or .xhtml.
要获取通过特定协议可用的所有数据集的当前列表，
- 对于 griddap：使用
  .csv, .htmlTable, .itx, .json, .jsonlCSV1, .jsonlCSV, .jsonlKVP, .mat, .nc, .nccsv, .tsv, or .xhtml.
- 对于tabledap ：使用
  .csv, .htmlTable, .itx, .json, .jsonlCSV1, .jsonlCSV, .jsonlKVP, .mat, .nc, .nccsv, .tsv, or .xhtml.
- 对于 WMS：使用
  .csv, .htmlTable, .itx, .json, .jsonlCSV1, .jsonlCSV, .jsonlKVP, .mat, .nc, .nccsv, .tsv, or .xhtml.
Griddap 和tabledap有许多可供您使用的 Web 服务。
- 数据访问表单只是简单的网页，用于生成请求数据（例如卫星和浮标数据）的 URL。数据可以是几种常见的文件格式。您的程序可以直接生成这些 URL。有关更多信息，请参阅griddap 文档和tabledap文档。
- Make A Graph 页面只是简单的网页，用于生成请求数据子集图表的 URL。图表可以采用几种常见的文件格式。您的程序可以直接生成这些 URL。有关更多信息，请参阅griddap 文档和tabledap文档。
- 要获取数据集的结构（包括变量名称和数据类型），请使用标准OPeNDAP .dds 请求。例如，
  https://coastwatch.pfeg.noaa.gov/erddap/zh-CN/griddap/jplMURSST41 .dds （网格数据）或
  https://coastwatch.pfeg.noaa.gov/erddap/zh-CN/tabledap/pmelTaoDySst .dds （表格数据）。
- 要获取数据集的元数据，请使用标准OPeNDAP .das 请求。例如，
  https://coastwatch.pfeg.noaa.gov/erddap/zh-CN/griddap/jplMURSST41 .das （网格数据）或
  https://coastwatch.pfeg.noaa.gov/erddap/zh-CN/tabledap/pmelTaoDySst .das （表格数据）。
- ERDDAP有一个特殊的表格数据集，称为allDatasets ，其中包含有关此ERDDAP中当前可用的所有数据集的数据。每个数据集都有一行。其中的列包含不同类型的信息（例如， datasetID 、标题、摘要、机构、许可证、数据访问表单 URL、制作图表 URL）。因为这是一个tabledap数据集，所以您可以使用tabledap数据请求来请求与约束匹配的特定列和行，并且可以以您喜欢的响应文件类型获取响应，例如 .html、 .xhtml 、 .csv、 .json 、 .jsonlCSV1 、 .jsonlCSV或.jsonlKVP 。
ERDDAP的其他协议也有 Web 服务可供使用。请参阅
- ERDDAP 的 WMS 文档
ERDDAP提供RSS订阅，以便您的计算机程序可以查明数据集是否已发生变化。
ERDDAP提供电子邮件/URL 订阅，每当数据集发生变化时都会通知您的计算机程序。
ERDDAP 提供多种转换器作为网页和 Web 服务：
ERDDAP有一个系统来跟踪过期数据集。请参阅该网页底部的选项。

如果您对更多链接有建议，请联系erd dot data at noaa dot gov 。

在Java程序中使用ERDDAP作为数据源

如上所述，由于Java程序可以访问网络上可用的数据，因此您可以编写一个Java程序来访问任何可公开访问的ERDDAP安装中的数据。

或者，由于ERDDAP是一个全开源程序，您也可以在自己的服务器（可公开访问或不可公开访问）上设置自己的ERDDAP副本，以提供自己的数据。您的Java程序可以从该ERDDAP副本中获取数据。请参阅设置您自己的ERDDAP 。

登录以访问私人数据集。

许多ERDDAP安装未启用身份验证，因此不为用户提供任何登录方式，也没有任何私人数据集。

某些ERDDAP安装确实启用了身份验证。目前， ERDDAP仅支持通过 Google 管理的电子邮件帐户进行身份验证，其中包括NOAA和许多大学的电子邮件帐户。如果ERDDAP启用了身份验证，则任何拥有 Google 管理的电子邮件帐户的人都可以登录，但他们只能访问ERDDAP管理员明确授权他们访问的私有数据集。有关从浏览器或通过脚本登录ERDDAP的说明，请参阅访问ERDDAP中的私有数据集。

ERDDAP版本

如果要在远程ERDDAP上使用新功能，可以通过发送请求来确定ERDDAP的版本号，以了解新功能是否可用，例如，
https://coastwatch.pfeg.noaa.gov/erddap/zh-CN/version
ERDDAP将发送带有ERDDAP ERDDAP号的文本响应。例如：
ERDDAP_version=2.26
如果收到HTTP 404 Not-Found错误消息，请将ERDDAP视为版本 1.22 或更低版本。

或者，您可以请求 version_string，其中可能包含其他信息。例如，
https://coastwatch.pfeg.noaa.gov/erddap/zh-CN/version_string
ERDDAP将发送一个文本响应，其中包含该ERDDAP的ERDDAP version_string。它将是一个浮点数（版本号），带有可选后缀“_”以及附加 ASCII 文本（无空格或控制字符）。例如：
ERDDAP_version_string=2.26_JohnsFork
如果收到HTTP 404 Not-Found错误消息，请将ERDDAP视为版本 1.80 或更低版本。