Text format(文本格式)
- 描述
- 概要
- 例子
- 1:[/data1.1/occs/list.txt?base_name=Dascillidae&limit=5](https://paleobiodb.org/data1.1/occs/list.txt?base_name=Dascillidae&limit=5)
- 2:[/data1.1/occs/list.txt?base_name=Dascillidae&showsource&count&limit=5](https://paleobiodb.org/data1.1/occs/list.txt?base_name=Dascillidae&showsource&count&limit=5)
- 3:[/data1.1/occs/list.txt?base_name=Dascillidae&noheader&limit=5](https://paleobiodb.org/data1.1/occs/list.txt?base_name=Dascillidae&noheader&limit=5)
描述
本文详细介绍文本响应格式。
概要
PBDB数据服务可以产生两种不同的文本格式的响应:tab分隔和逗号分隔。这两种格式在默认情况下都使用标准的PBDB字段名,这意味着您可以使用它们执行与使用PBDB下载文件相同的操作。它们之间主要的不同有:
- 响应中可能会含有PBDB标准下载中没有的新字段名。
- 列的顺序可能与旧下载文件中的顺序不同。
- 根据您提供的参数,可能会含有一些可选的表头内容。
- 文本是用UTF-8编码的,而不是像PBDB 标准文件那样用ISO-8859-1编码。
您可以从下列3种后缀中选择:
- .csv:以逗号分隔的文本格式生成下载文件。大多数浏览器会将此文件直接保存到磁盘;如果您希望立即在浏览器选项卡中看到它,那么可以使用后缀.txt,或者包含参数textresult。
- .tsv:以tab分隔的文本格式生成下载文件。如果希望在浏览器选项卡中查看结果,请包含参数textresult。
- .txt:在浏览器选项卡中以逗号分隔的文本格式显示结果。然后,您将能够使用浏览器中的“save Page As…”菜单项将该文件保存到磁盘,这将产生与使用csv后缀相同的结果。
注意,如果结果集的大小较小或中等,则应该只使用textreresult参数或**.txt**后缀。如果您试图在浏览器选项卡中直接显示一个大的结果集,可能需要很长时间来呈现,并使用大量的内存。
此外,您可以选择包括以下一个或多个URL参数:
- noheader:如果指定了此参数,则不会包含任何标头内容。如果有的话,文件的第一行将是第一个数据记录。如果没有找到数据记录,则该文件将为空。这个参数不需要任何值。
- linebreak:如果此参数的值为cr,则每一行将以单个回车字符结束,而不是标准的回车/换行序列。
响应体由一系列包含逗号分隔或制表符分隔值的行组成。文件的初始部分可能包含以下部分或全部行:
- Data Source: 如果指定了参数showsource,则会显示这一行。第二列中的值将是该数据源的名称。
- Data Source URL: 如果指定了参数showsource,则会显示这一行。第二列中的值将是此数据源的基URL。
- Data License: 如果指定了参数showsource,则会显示这一行。第二列中的值将是提供该数据的许可。
- Data License URL: 如果指定了参数showsource,则会显示这一行。第二列中的值将是一个URL,可以从中获取许可条款。
- Documentation URL: 如果指定了参数showsource,则会显示这一行。第二列中的值将是一个URL,它提供了关于用于获取该数据的URL路径的文档。这个URL将记录参数和响应字段。这一信息可能有助于指导以后对这一数据的解读。
- Data URL: 如果指定了参数showsource,则会显示这一行。第二列中的值将是用于获取该数据的实际URL。如果将此数据集保存到磁盘,则包含的行将允许某人稍后重复此查询。
- Access Time: 如果指定了参数showsource,则会显示这一行。第二列中的值将是访问该数据的日期和时间(GMT)。如果将此数据集保存到磁盘,则包含的行将使其能够根据访问时间与其他数据集进行比较。
- Parameters: 如果指定了参数showsource,则会显示这一行。每个参数后面都有一行,给出用于生成该结果的参数名和值。如果将此数据集保存到磁盘,则参数信息可能有助于记录数据是如何选择的,它包括什么,以及不包括什么。
- Records Found: 如果指定了参数count,就会出现这一行。第二列中的值将是与主查询匹配的记录数。
- Records Returned: 如果指定了参数count,就会出现这一行。第二列中的值将是实际返回的记录数。这可能少于找到的记录总数,因为结果集的大小默认限制为500。您可以使用limit来覆盖它。
- Record Offset: 如果指定了参数count,并且参数offset的值大于零,则会出现这一行。第二列中的值将是在结果集开始时跳过的记录数。
- Warning: 如果在执行查询期间生成了任何警告,则会出现一个或多个这样的行。警告消息将出现在第二列中。
- Records: 如果该表中迄今为止提到的任何行出现在输出中,那么这一行将立即出现在数据表头之前。它用于从数据中标记出补充标头内容。
数据标头
除非指定了参数noheader,否则数据标题行总是在第一个数据行之前。标题行将包含每一列的名称。
数据记录将跟随这个表头内容,每行一个记录,直到文件结束。
例子
例如,下面的URL将产生以下输出,看起来非常类似于PBDB 标准下载:
1:/data1.1/occs/list.txt?base_name=Dascillidae&limit=5
"occurrence_no","record_type","reid_no","superceded","collection_no","taxon_name","taxon_rank","taxon_no","matched_name","matched_rank","matched_no","early_interval","late_interval","early_age","late_age","reference_no"
"915582","occurrence","","","113371","Parelateriformius n. gen. communis n. sp.","species","176462","Parelateriformius communis","species","176462","Callovian","Oxfordian","166.1","157.3","35052, 35052"
"915583","occurrence","","","113371","Parelateriformius villosus n. sp.","species","176463","Parelateriformius villosus","species","176463","Callovian","Oxfordian","166.1","157.3","35052, 35052"
"915584","occurrence","","","113371","Parelateriformius capitifossus n. sp.","species","176464","Parelateriformius capitifossus","species","176464","Callovian","Oxfordian","166.1","157.3","35052, 35052"
"915585","occurrence","","","113371","Parelateriformius mirabdominis n. sp.","species","176465","Parelateriformius mirabdominis","species","176465","Callovian","Oxfordian","166.1","157.3","35052, 35052"
"1054041","occurrence","","","128550","Dascillus shandongianus","species","241265","Dascillus shandongianus","species","241265","Burdigalian","","20.44","15.97","16579, 16579"
2:/data1.1/occs/list.txt?base_name=Dascillidae&showsource&count&limit=5
这个例子包含一些额外的表头信息,以*Records:*行结尾。
"Data Provider","The Paleobiology Database"
"Data Source","The Paleobiology Database"
"Data License","Creative Commons CC-BY"
"License URL","http://creativecommons.org/licenses/by/4.0/"
"Documentation URL","http://paleobiodb.org/data1.1/occs/list_doc.html"
"Data URL","http://paleobiodb.org/data1.1/occs/list.txt?base_name=Dascillidae&showsource&count&limit=5"
"Access Time","Sat 2023-05-06 07:52:15 GMT"
"Title","PBDB Data Service"
"Parameters:"
"","base_name","Dascillidae"
"","ident","latest"
"","limit","5"
"Elapsed Time","0.00317"
"Records Found","33"
"Records Returned","5"
"Records:"
"occurrence_no","record_type","reid_no","superceded","collection_no","taxon_name","taxon_rank","taxon_no","matched_name","matched_rank","matched_no","early_interval","late_interval","early_age","late_age","reference_no"
"915582","occurrence","","","113371","Parelateriformius n. gen. communis n. sp.","species","176462","Parelateriformius communis","species","176462","Callovian","Oxfordian","166.1","157.3","35052, 35052"
"915583","occurrence","","","113371","Parelateriformius villosus n. sp.","species","176463","Parelateriformius villosus","species","176463","Callovian","Oxfordian","166.1","157.3","35052, 35052"
"915584","occurrence","","","113371","Parelateriformius capitifossus n. sp.","species","176464","Parelateriformius capitifossus","species","176464","Callovian","Oxfordian","166.1","157.3","35052, 35052"
"915585","occurrence","","","113371","Parelateriformius mirabdominis n. sp.","species","176465","Parelateriformius mirabdominis","species","176465","Callovian","Oxfordian","166.1","157.3","35052, 35052"
"1054041","occurrence","","","128550","Dascillus shandongianus","species","241265","Dascillus shandongianus","species","241265","Burdigalian","","20.44","15.97","16579, 16579"
3:/data1.1/occs/list.txt?base_name=Dascillidae&noheader&limit=5
展示一下没有表头信息的响应结果:
"915582","occurrence","","","113371","Parelateriformius n. gen. communis n. sp.","species","176462","Parelateriformius communis","species","176462","Callovian","Oxfordian","166.1","157.3","35052, 35052"
"915583","occurrence","","","113371","Parelateriformius villosus n. sp.","species","176463","Parelateriformius villosus","species","176463","Callovian","Oxfordian","166.1","157.3","35052, 35052"
"915584","occurrence","","","113371","Parelateriformius capitifossus n. sp.","species","176464","Parelateriformius capitifossus","species","176464","Callovian","Oxfordian","166.1","157.3","35052, 35052"
"915585","occurrence","","","113371","Parelateriformius mirabdominis n. sp.","species","176465","Parelateriformius mirabdominis","species","176465","Callovian","Oxfordian","166.1","157.3","35052, 35052"
"1054041","occurrence","","","128550","Dascillus shandongianus","species","241265","Dascillus shandongianus","species","241265","Burdigalian","","20.44","15.97","16579, 16579"