Dataset

Base definition

{
    "kind": "dataset",
    "id": string,
    "qualifiedReference": string,
    "scopedReference": string,
    "referenceId": string,
    "name": string,
    "url": string,
    "uri": string,
    "doi": string,
    "owner": {
      user.base | organization.base // See user or organization resource definition
    }
}

List definition

In addition to the base definition, any dataset resource returned by a list request will contain the following properties:

{
    "description": string,
    "labels": string[], // Only present if you are an administrator
    "accessLevel": string("overview"|"metadata"|"sample"|"data"|"edit"),
    "publicAccessLevel": string("none"|"overview"|"metadata"|"sample"|"data"|"edit"),
    "createdAt": integer, 
    "updatedAt": integer, 
    "tableCount": integer,
    "numBytes": integer, 
    "totalNumBytes": integer,
    "totalActiveTabularBytes": integer,
    "totalInactiveTabularBytes": integer,
    "totalRawFileBytes": integer,
    "temporalRange": [integer, integer], 
    "temporalPrecision": string,
    "geoBBox": {
        "westLongitude": number,
	"eastLongitude": number,
	"northLatitude": number,
	"southLatitude": number
    },
    "sampleConfiguration": null | {
        "variableName": null | string,
        "targetRatio": float
    }
}

Get definition

In addition to the base and list definition, any dataset resource returned by a get request will contain the following properties:

{
    "methodologyMarkdown": string,
    "usageMarkdown": string,
    "contactInfo": string,
    "links": [
        { 
            "title": string, 
            "url": string 
        }
    ],
    "supportingFiles": [
        { 
            "name": string, 
            "url": string, 
            "accessLevel": string("overview"|"metadata"|"sample"|"data"),
            "mimeType": string,
            "size": int 
        }
    ],
    "customDocumentationSections": [
        {
             "title": string,
             "accessLevel": string("overview"|"metadata"|"sample"|"data"),
             "markdownContent": string  
        }    
    ],
    "tags": [
        {
            "name": string
        }
    ],
    "version": object(version.base),
    "currentVersion": object(version.base),
    "nextVersion": object(version.base)
}

Documentation

Fields

Base

kind

string

The resource type.

string

A unique, persistent identifier for the dataset.

qualifiedReference

string The fully qualified reference for the dataset, of the form username.dataset_reference. E.g., demo.ghcn_daily_weather_data:v1_1:7br5

scopedReference

string The canonical reference for the dataset, e.g., ghcn_daily_weather_data:v1_1:7br5

referenceId

string A persistent, 4-character identifier for this dataset. Will always be unique across all datasets owned by the user / organization.

name

string

The name of the dataset

url

string

The table's url discoverable via the web interface.

uri

string

The fully qualified URI of the dataset, for use in generating calls to this API.

For example, /datasets/demo.ghcn_daily_weather_data:v1_1:7br5

doi

string The permanent reference to the dataset, using the digital object identifier system. Will be of the form 10.1109/5.771073 Will currently only be present for datasets hosted by organizations that have a DOI registry configured.

owner

object

The owner of the dataset. Will either be an organization base definition or a user base definition.

List

createdAt

integer

When the dataset was created. Stored as milliseconds since the epoch (1970-01-01).

updatedAt

integer

When the dataset was updated. Stored as milliseconds since the epoch (1970-01-01).

accessLevel

string

The accessLevel of the table for the current user, ignoring the access token being used. Will be one of: "none", "overview", "metadata", "data"

publicAccessLevel

string

The accessLevel of the table to unauthenticated users. Will be one of: "none", "overview", "metadata", "data"

description

string

A user-provided description of the dataset. Corresponds to the "abstract" show on the dataset overview.

tableCount

integer

The number of tables on the dataset

numBytes

integer

The size of all tables stored across the current version of the dataset.

totalNumBytes

integer

The total storage size of this dataset, across all versions.

totalActiveTabularBytes

integer The total "active" bytes across all tables in this dataset, across all versions. Rows within a table become active once queried.

totalInactiveTabularBytes

integer The total "inactive" bytes across all tables in this dataset, across all versions. A particular row of a table becomes inactive when it hasn't been queried in 90 days.

totalRawFileBytes

integer The total number of bytes across all non-tabular files stored on this dataset, across all versions.

temporalRange

array(integer, integer)

Will be null if no range has been specified. A tuple representing the start and end values for the temporal range. Stored as milliseconds since the epoch (1970-01-01).

Note that in the case where temporalPrecision is "year" or "date", the upper bound of this value will store one millisecond before the next offset. For example:

[1980, 1982]

=> [1980-01-01 00:00:00.000, 1982-12-31 23:59:59.999]

[1990-09-19, 1990-09-24]

=> [1990-09-19 00:00:00.000, 1990-09-24 23:59:59.999]

temporalPrecision

string

The precision of the temporal range. Will be one of "year", "date", "dateTime"

geoBBox

object An object describing the geographic bounding box of all geographic variables in the dataset. Will only be present for datasets containing "geography" variables, and if those variables' summary statistics have been computed (computation is performed automatically when a version of a dataset is released).

geoBBox .westLongitude .eastLongitude .northLatitude .southLatitude

number Each property represents one side of the bounding box, expressed in numeric degrees.

sampleConfiguration

object | null If a sample is present on this dataset, contains information about the sample configuration. Otherwise, will be null

sampleConfiguration.variableName

string The name of the variable that the sample is based on. May be null if the sample is a simple random sample.

sampleConfiguration.targetRatio

float The approximate ratio of records in the sample tables compared to the unsampled tables.

Get

methodologyMarkdown

string The methodology information documented for the dataset, in markdown format. May be null.

usageMarkdown

string The usage information documented for the dataset, in markdown format. May be null.

contactInfo

string The contact information documented for the dataset, as free text. May be null.

customDocumentationSections[]

array(object)

An array of custom documentation sections for the dataset

customDocumentationSections[].title

string

The title of the custom section

customDocumentationSections[]

.accessLevel

string

The minimum accessLevel required to view the custom section. Will be one of overview,metadata, data

customDocumentationSections[]

.markdownContent

string

The content of the documentation, stored as markdown. This field will be null if the current caller doesn't have the appropriate access level to view this section.

links

array(object)

An array of external links with related content to the dataset

links[].title

string The link title

links[].url

string The link URL

supportingFiles

array(object)

An array of hosted files with supporting content related to the dataset

supportingFiles[].name

string The name of the supporting file

supportingFiles[].url

string The download url of the supporting file. This URL will only be accessible if the calling user has the appropriate accessLevel to view this supporting file

supportingFiles[].accessLevel

string The accessLevel required to view the supporting file. Will be one of overview,metadata, data

supportingFiles[].mimeType

string The recorded MIME type of the uploaded file

supportingFiles[].size

integer The size, in bytes, of the supporting file