DESCRIPTION

This page describes the JSON response format in detail.

SYNOPSIS

The JSON (JavaScript Object Notation) format is selected by ending a URL path with the suffix .json. This format is very flexible, and is intended for use by web applications built on top of this data service as well as for transmitting content to and from other databases. JSON responses are always encoded in UTF-8.

The body of a response in this format consists of a single JSON object, containing one or more of the following fields:

records

The value of this field is an array of objects, each representing a record from the database.

This field will always be present if the URL path and parameters are interpreted to be a valid query, but the array may be empty if the query does not match any records.

records_found

This field will be present if the parameter count was specified. Its value will be the number of records matched by the main query.

records_returned

This field will be present if the paramter count was specified. Its value will be the number of records actually returned. <%- IF request.default_limit %> This may be less than the total number of records found, because the size of the result set is limited by default to <% request.default_limit %>. You can override this using the limit parameter. <%- END %>

record_offset

This field will be present if the parameter count was specified, and if the parameter offset was specified with a value greater than zero. The value in the second column will be the number of records that were skipped at the beginning of the result set.

data_source

This field will be present if the parameter datainfo was specified. Its value will be the name of this data source.

documentation_url

This field will be present if the parameter datainfo was specified. Its value will be a URL that provides documentation about the URL path used to fetch this data. This URL will document both the parameters and the response fields. This information may be helpful in guiding the later interpretation of this data.

data_url

This field will be present if the parameter datainfo was specified. Its value will be the actual URL that was used to fetch this data. If this dataset is saved to disk, the included field will allow someone to later repeat this query.

access_time

This field will be present if the parameter datainfo was specified. Its value will be the date and time time (GMT) at which this data was accessed. If this dataset is saved to disk, the included field will enable it to be compared with other datasets on the basis of access time.

parameters

This field will be present if the parameter datainfo was specified. Its value will be an object whose fields represent the parameters and values that were used to generate this result. If this dataset is saved to disk, the parameter information may be helpful in documenting how the data was selected, what it includes, and what it does not include.

warnings

This field will be present if any warnings were generated during the execution of the query. Its value will be an array of strings, each representing a warning message.

errors

This field will be present if a fatal error condition was encountered. Its value will be an array of strings, each representing an error message. In general, if this field is present then none of the others will be.

status_code

This field will be present if the HTTP status code is anything other than 200. Its value will be one of the following:

400

One or more of the URL parameters was invalid. The reasons will be given by the field errors. This request should not be repeated without modification.

401

This request requires authentication. Note that the authentication module has not yet been added to the data service, so you should not be seeing this yet.

404

The URL path was invalid. This request should not be repeated without modification.

500

An internal error occurred. If this condition persists, you should contact the server administrator. Otherwise, the request may be resubmitted later.

For example, consider the following URL path:

• op:single.json?state=WI

The body of the response is as follows:

    {
	"records": [
	    {
		"name": "Wisconsin",
		"abbrev": "WI",
		"region": "MW",
		"pop2010": 5686986
	    }
	]
    }

This body is made up of an object containing the field "records", whose value is an array. Each element of the array represents a single record fetched from the database. The definitions of the various fields can be found on the documentation page for this URL path: node:single#RESPONSE.

Many URL paths will, of course, return multiple records. For example:

• op:list.json?state=wi,mn,il&count

    {
	"elapsed_time": 0.000283,
	"records_found": 3,
	"records_returned": 3,
	"records": [
	    {
		"name": "Illinois",
		"abbrev": "IL",
		"region": "MW",
		"pop2010": 12830632
	    },
	    {
		"name": "Minnesota",
		"abbrev": "MN",
		"region": "MW",
		"pop2010": 5303925
	    },
	    {
		"name": "Wisconsin",
		"abbrev": "WI",
		"region": "MW",
		"pop2010": 5686986
	    }
	]
    }

This response body contains multiple records, but is otherwise structured identically. Note the presence of the count parameter, which causes the inclusion of the fields elapsed_time, records_found, and records_returned.

Finally, consider the following URL:

• op:list.json?state=WI,IX&foo=1

    {
	"status_code": 400,
	"errors": [
	    "unknown parameter 'foo'"
	],
	"warnings": [
	    "the value of 'state' must be a valid state name or abbreviation"
	]
    }

This response body conveys both an error and a warning, along with a status code of 400 (Bad Request) which indicates a problem with the URL parameters.