描述

本文详细介绍JSON响应格式。

概要

JSON (JavaScript对象表示法)格式是通过以.json后缀结束URL路径来选择的。这种格式非常灵活，常用于构建在此数据服务之上的web应用程序，以及与其他数据库之间传输内容。JSON响应总是以UTF-8编码。

这种格式的响应体由一个JSON对象组成，包含以下一个或多个字段:

• records：该字段的值是一组对象，每一个对象表示数据库中的一条记录。如果URL路径和参数被解释为有效查询，则该字段将始终存在，但如果查询不匹配任何记录，则数组可能为空。
• records_found：如果指定了参数count，则该字段将出现。它的值是查询匹配的记录数。
• records_returned：如果指定了参数count，则该字段将出现。它的值将是实际返回的记录数。这可能少于找到的记录总数，因为结果集的大小默认限制为500。您可以使用limit参数来覆盖它。
• record_offset：如果指定了参数count，并且使用大于零的值指定了offset，则该字段将出现。第二列中的值将是在结果集开始时跳过的记录数。
• data_source：如果指定了showsource，该字段将会出现。它的值将是该数据源的名称。
• data_source_url：如果指定了showsource，该字段将会出现。它的值将是该数据源的基URL。
• data_license：如果指定了showsource，该字段将会出现。它的值将是提供该数据的许可。
• data_license_url：如果指定了showsource，该字段将会出现。它的值将是一个URL，可以从中获取许可条款。
• documentation_url：如果指定了showsource，该字段将会出现。它的值将是一个URL，该URL提供了关于用于获取该数据的URL路径的文档。这个URL将记录参数和响应字段。这一信息可能有助于指导以后对这一数据的解读。
• data_url：如果指定了showsource，该字段将会出现。它的值将是用于获取该数据的实际URL。如果将此数据集保存到磁盘，则包含的字段将允许某人稍后重复此查询。
• access_time：如果指定了showsource，该字段将会出现。它的值将是访问该数据的日期和时间(GMT)。如果将此数据集保存到磁盘，则包含的字段将使其能够根据访问时间与其他数据集进行比较。
• parameters：如果指定了showsource，该字段将会出现。它的值将是一个对象，其字段表示用于生成此结果的参数和值。如果将此数据集保存到磁盘，则参数信息可能有助于记录数据是如何选择的，它包括什么，以及不包括什么。
• warnings：如果在执行查询期间生成了任何警告，则将显示此字段。它的值将是一个字符串数组，每个字符串表示一条警告消息。
• errors：如果遇到错误，将显示此字段。它的值将是一个字符串数组，每个字符串代表一个错误消息。通常，如果该字段存在，则其他字段都不存在。
• status_code：如果HTTP状态码不是200，就会出现这个字段。它的值将是以下之一：
  400：一个或多个URL参数无效。具体原因将在errors中显示。此请求未经修正不应再次提交。
  401：此请求需要身份验证。请注意，身份验证模块还没有添加到数据服务中，因此您还不应该看到这一点。
  404：URL路径无效。此请求未经修正不应再次提交。
  500：发生内部错误。如果这种情况仍然存在，您应该联系服务器管理员。或者，稍后重新提交请求。

例子

例1：/data1.1/colls/single.json?id=1003

{"records": [{"oid": 1003,"typ": "collection","lng": -94.804169,"lat": 37.331112,"prc": "seconds","nam": "USGS 7848-Cherokee Co., Kansas","noc": 1,"oei": "Desmoinesian","rid": 33}]
}

例2：/data1.1/config.json?show=clusters&count

{
"elapsed_time":0.000109,
"records_found":3,
"records_returned":3,
"records": [
{"cfg":"clu","lvl":"1","deg":"6.00000","cnt":"821","mco":"5670","moc":"43550"},
{"cfg":"clu","lvl":"2","deg":"2.00000","cnt":"3807","mco":"2205","moc":"16165"},
{"cfg":"clu","lvl":"3","deg":"0.50000","cnt":"17917","mco":"932","moc":"12081"}
]
}

例3：/data1.1/colls/list.json?lngmin=50.0&show=foo

{ "status_code": 400,
"errors": ["you must specify both of 'lngmin' and 'lngmax' if you specify either of them"],
"warnings": ["bad value 'foo' for 'show': must be one of 'bin', 'attr', 'ref', 'loc', 'paleoloc', 'prot', 'time', 'strat', 'stratext', 'lith', 'lithext', 'geo', 'rem', 'ent', 'entname', 'crmod'"] }

我的备注

本文中提及的参数count和showsource，应该分别是rowcount和datainfo。