CitSci.org APIs

Note: These APIs are currently under development and do not interact with the live database.

Overview

This document is a prequel to the CitSci API Requirements Documentation. It provides a big picture view of how the different APIs are used and the order in which to use them. These APIs are web services and can be used in any environment to programmatically access the Citsci.org website. In fact, these web services can be called from a web application, an Android application, an iOS application and even a desktop application.

The Steps

  1. Register your application with CitSci.org
  2. Get the access token
  3. Use the GetProjectList API to get a list of the projects associated with a defined user
  4. Use the GetDataSheet API to get the data sheet(s) associated with a selected project
  5. Use the UploadObservation API to upload an observation to Citsci.org

Register

The registration process assigns an application or web site credentials to permit access to the features of the CitSci.org website APIs.

Get the access token

The login process is described in detail in the API Requirements Document. This step provides the application with an access token, a refresh token, and a token expiration date. The access token is used as part of the request to all other APIs. If the access token has expired, the current time and date is later than the expiration time and date, then the user must call the refresh token API to get an new access token. The access token is returned in JSON format only.

Refresh the access token

The access token expires one hour after it is requested. One of the values returned by the GetAccessToken API is the expiration time and date. If the current time and date is later than the expiration time and date, the application must refresh their access token. Refreshing the access token is described in detail in the API Requirements Document. The new access token is returned to the application in JSON only.

API descriptions

Get user profile

Getting the user's profile information allows the application to display info such as the user's first and last name, if desired. The API is sent the access token and returns the user's first name, last name, and login alias in either JSON or XML depending on the user’s specification. Getting the user's profile information is described in the Get User Profile section.

Get project list

Under normal circumstances, getting the project list is the first activity the application performs after acquiring the access token. The API returns the project list in either JSON or XML depending on the user’s specification. Getting the project list is described in detail in the Get Project List section.

Get datasheets

Data sheets are associated with a specific project. The application specifies the access token along with a project ID. The API returns the data sheet in either JSON or XML depending on the user’s specification. The process of acquiring a data sheet is described in detail in the Get Datasheets section.

Upload observations

Once an observation has been completed, it needs to be uploaded to the CitSci.org server. The application is required to provide the access token and the mode, either XML or JSON (along with the observation).


Get User Profile

Fetch the details of the logged in user given the access token.

Request URL

//ibis-live1.nrel.colostate.edu/app.php/API/GetProfile

Request Parameters

The following query parameters may be passed in the request to control the output:

Parameter Required Value Description
Token Yes
Type: string

The access token for this session provided by oAuth authorization.

Response Fields

The response is composed of the logged in user’s basic information.

Field Value Description
FirstName
Type: string

First name of logged in user.

LastName
Type: string
Last name of logged in user.
Login
Type: string
Login alias of logged in user.

Sample Request

https://ibis-live1.nrel.colostate.edu/app.php/API/GetProfile?Token=AUhJb0qPBpiJbbcXN0XFJYIDa80o5hksJHgYegUx

Sample Response (JSON)

{
    "status": "Success",
    "message": "",
    "data": {
        "FirstName": "Samantha",
        "LastName": "Stephens",
        "Login": "SStephens"
    }
}


Get Project List

Fetch details of the project(s) which the logged in user is a member of.

Request URL

//ibis-live1.nrel.colostate.edu/app.php/API/GetProjectList

Request Parameters

The following query parameters may be passed in the request to control the output:

Parameter Required Value Description
Token Yes
Type: string

The access token for this session provided by oAuth authorization.

Mode Yes
Type: string
Options: XML, json

Preferred format of API response.

Response Fields

The response lists information pertaining to projects which the logged in user is a member of.

Field Value Description
ProjectID
Type: string

Unique ID of the project in database.

ProjectName
Type: string
Name of the project.
Status
Type: Integer

Status of the project. Status types are given below:

Value Description
0 Unknown
1 Starting
2 In progress
3 Completed
Description
Type: string
Description of the project.
PinLatitude
Type: float
Latitude coordinate of the project headquarters.
PinLongitude
Type: float
Longitude coordinate of the project headquarters.

Sample Request

https://ibis-live1.nrel.colostate.edu/app.php/API/GetProjectList?Token=WJ2DlSAAoIwQnZxfyPtBWZTiyp14PrCYj3ESz6BN&Mode=json

Sample Response (JSON)

{
    "status": "Success",
    "message": "",
    "data": [
        {
            "ProjectID": "444",
            "ProjectName": "A Shorter Test Project Title",
            "Status": "2",
            "Description": "This is a training for member of the Central Virginia, Central Blue Ridge, Roanoke, and Central Piedmont Chapters.",
            "PinLatitude": "9.9473409999999998",
            "PinLongitude": "76.377472999999995"
        },
        {
            "ProjectID": "380",
            "ProjectName": "Bale Mountain Medicinal Plant Mapping ",
            "Status": "2",
            "Description": "",
            "PinLatitude": null,
            "PinLongitude": null
        }
    ]
}


Get Datasheets

Fetch the datasheet information related to the logged in user's projects.

Request URL

//ibis-live1.nrel.colostate.edu/app.php/API/GetDatasheets

Request Parameters

The following query parameters may be passed in the request to control the output:

Parameter Required Value Description
Token Yes
Type: string

The access token for this session provided by oAuth authorization.

Mode Yes
Type: string
Options: XML, json

Preferred format of API response.

ProjectID Yes
Type: Integer

Unique ID of the project in database.

Response Fields

The response is composed of datasheet(s) information related to the logged in user's project(s).

Field Value Description
DataSheetID
Type: integer

Unique ID of the datasheet in the database.

Name
Type: string
Name of the datasheet specified by the datasheet creator.
AreaSubTypeID
Type: integer
Location type collected by datasheet. There are too many values to list. (Ex. AreaSubTypeID="11" specifies a single "point" location).
Predefined
Type: binary

Indicates whether or not datasheet uses a predefined location picklist. Binary options are given below:

Value Description
0 Datasheet does not contain predefined location picklist. The user manually enters location coordinates.
1 Datasheet does contain predefined location picklist. The user chooses from a defined list of location names, specified by the datasheet creator.
Attributes
Type: list
Contains list of datasheet fields.
ID
Type: integer
Unique ID of this datasheet field in database. Equivalent to FormEntryID.
AttributeTypeID
Type: integer
Unique ID of attribute type in database. Attribute types are the measurements that make up a datasheet (ex. Presence, height, etc.)
AttributeValueID
Type: integer
Unique ID of measurement value in database. Measurement values are the options related to a categorical measurement. (ex. "Yes", "No" for the measurement "Presence".)
ParentFormEntryID
Type: integer
Unique ID of the datasheet field associated with this measurement. If not null, this measurement is related to an organism with datasheet field ID = ParentFormEntryID.
HowSpecified
Type: integer

Indicates how the data entered into the datasheet field is specified. Options are given below:

Value Description
1 Data is entered into the datasheet field by the user. Data entered can be text or numerical.
2 Data is selected from a picklist of options by the user. This applies to categorical measurements.
3 Data is defined or specified by the creator of the datasheet, and the user cannot change the answer.
4 This datasheet field is hidden to the user, and used to submit data not entered by the user.
OrderNumber
Type: integer
Number used to set the order of "site" related datasheet fields on the datasheet. This order is specified by the datasheet creator.
UnitID
Type: integer
Unique ID of the unit type associated with this measurement, if specified by the datasheet creator. (Ex. ID of the unit type "meters" associated with the measurement "Distance from road".)
SubplotTypeID
Type: integer
Unique ID of the subplot associated with this measurement, if specified by the datasheet creator.
OrganismInfoID
Type: integer
Unique ID of the organism defining the datasheet field. If not null, the datasheet field is a single organism. (Ex. "Chelonia mydas")
Picklist
Type: binary

Indicates whether or not this datasheet field is an organism picklist. Binary options are given below:

Value Description
0 Datasheet field is not an organism picklist.
1 Datasheet field is an organism picklist.
AttributeCategoryID
Type: integer

Classifies the datasheet field as relating to the "site" or an "organism". Categories are given below:

Value Description
1 Datasheet field is classified as an "organism" related measurement (Ex. "carapace length" of a turtle).
7 Datasheet field is classified as a "site" related measurement (Ex. "Air temperature").
MinimumValue
Type: float
Minimum value restriction of data entered for this measurement, if specified by the datasheet creator. Applies to numeric measurements only.
MaximumValue
Type: float
Maximum value restriction of data entered for this measurement, if specified by the datasheet creator. Applies to numeric measurements only.
Description
Type: string
Description of the measurement. This description is visible next to the measurement on a datasheet.
ValueType
Type: integer

Specifies the type of data entered into this datasheet field. Categories are given below:

Value Description
1 Categorical (Ex. the values of "Yes" or "No" are categorical data types associated with the measurement "Presence")
2 Numeric (decimal)
3 Numeric (integer)
4 Boolean (T/F)
5 String (text)
6 Date (date/time)
OrganismList
Type: list

List of organisms the datasheet creator has specified for an organism picklist. Each organism in the list will have two fields associated with it:

Field Value Description
ID
Type: integer
Unique ID of the organism in the system. Equivalent to "OrganismInfoID" (described above).
Name
Type: string
Name of the organism: "Scientific name (common name)".
AttributeValuesPossible
Type: list

List of options for a categorical datasheet field, specified by datasheet creator. Each option in the list will have three fields associated with it:

Field Value Description
ID
Type: integer
Unique ID of measurement value in database. Equivalent to "AttributeValueID" (above).
Name
Type: string
Name of the the measurement value.
Description
Type: string
Description of the the measurement value.
UnitDetails
Type: list

List details of the unit associated with this datasheet field. Each unit in the list will have two fields associated with it:

Field Value Description
Name
Type: string
Name of the unit (Ex. "feet").
Abbreviation
Type: string
Abbreviated name of the unit (Ex. "ft").

Sample Request

https://ibis-live1.nrel.colostate.edu/app.php/API/GetDatasheets?Token=9m2tkZ5oClFSf6Mp2mjSNpy2S5hgPPlVIIJEw3Go&Mode=json&ProjectID=444

Sample Response (JSON)

{
    "status": "Success",
    "message": "",
    "data": [
        {
            "DataSheetID": "509",
            "Name": "NO Predefined Locations",
            "AreaSubTypeID": "11",
            "Predefined": "0",
            "Attributes": [
                {
                    "ID": "3479",
                    "AttributeTypeID": null,
                    "AttributeValueID": null,
                    "ParentFormEntryID": null,
                    "HowSpecified": null,
                    "OrderNumber": null,
                    "UnitID": null,
                    "SubplotTypeID": null,
                    "OrganismInfoID": null,
                    "Picklist": "1",
                    "AttributeCategoryID": null,
                    "MinimumValue": null,
                    "MaximumValue": null,
                    "Description": null,
                    "ValueType": null,
                    "OrganismList": [
                        {
                            "ID": "213342",
                            "Name": "Acanthochelys pallidipectoris (Acanthochelys pallidipectoris)"
                        },
                        {
                            "ID": "213343",
                            "Name": "Amyda cartilaginea (Amyda cartilaginea)"
                        },
                        {
                            "ID": "213344",
                            "Name": "Arizona elegans (Arizona elegans  candida)"
                        }
                    ]
                },
                {
                    "ID": "3490",
                    "AttributeTypeID": "334",
                    "AttributeValueID": null,
                    "ParentFormEntryID": "3479",
                    "HowSpecified": "2",
                    "OrderNumber": null,
                    "UnitID": null,
                    "SubplotTypeID": null,
                    "OrganismInfoID": null,
                    "Picklist": null,
                    "AttributeCategoryID": "1",
                    "MinimumValue": "0.0",
                    "MaximumValue": "0.0",
                    "Description": "What was the koala doing? (e.g. sleeping, eating)",
                    "ValueType": "1",
                    "UnitDetails": {
                        "Name": "Unknown",
                        "Abbreviation": null
                    },
                    "AttributeValuesPossible": [
                        {
                            "ID": "744",
                            "Name": "Sleeping",
                            "Description": ""
                        },
                        {
                            "ID": "745",
                            "Name": "Eating",
                            "Description": ""
                        }
                    ]
                },
                {
                    "ID": "3497",
                    "AttributeTypeID": "73",
                    "AttributeValueID": null,
                    "ParentFormEntryID": null,
                    "HowSpecified": "1",
                    "OrderNumber": "2",
                    "UnitID": "26",
                    "SubplotTypeID": null,
                    "OrganismInfoID": null,
                    "Picklist": null,
                    "AttributeCategoryID": "7",
                    "MinimumValue": "0.0",
                    "MaximumValue": "125.0",
                    "Description": "",
                    "UnitDetails": {
                        "Name": null,
                        "Abbreviation": null
                    },
                    "ValueType": "2"
                },
                {
                    "ID": "3498",
                    "AttributeTypeID": "7",
                    "AttributeValueID": null,
                    "ParentFormEntryID": "3479",
                    "HowSpecified": "2",
                    "OrderNumber": null,
                    "UnitID": null,
                    "SubplotTypeID": null,
                    "OrganismInfoID": null,
                    "Picklist": null,
                    "AttributeCategoryID": "1",
                    "MinimumValue": null,
                    "MaximumValue": null,
                    "Description": null,
                    "ValueType": "1",
                    "UnitDetails": {
                        "Name": "Unknown",
                        "Abbreviation": null
                    },
                    "AttributeValuesPossible": [
                        {
                            "ID": "15",
                            "Name": "Female",
                            "Description": null
                        },
                        {
                            "ID": "16",
                            "Name": "Male",
                            "Description": null
                        },
                        {
                            "ID": "17",
                            "Name": "Asexual",
                            "Description": null
                        },
                        {
                            "ID": "18",
                            "Name": "Hermaphroditic",
                            "Description": null
                        },
                        {
                            "ID": "219",
                            "Name": "Unknown",
                            "Description": "Sex not able to be determined in the field"
                        }
                    ]
                },
                {
                    "ID": "3504",
                    "AttributeTypeID": "75",
                    "AttributeValueID": null,
                    "ParentFormEntryID": null,
                    "HowSpecified": "2",
                    "OrderNumber": "4",
                    "UnitID": null,
                    "SubplotTypeID": null,
                    "OrganismInfoID": null,
                    "Picklist": null,
                    "AttributeCategoryID": "7",
                    "MinimumValue": "0.0",
                    "MaximumValue": "0.0",
                    "Description": "Percent cloud cover",
                    "ValueType": "1",
                    "UnitDetails": {
                        "Name": "Centigrade (Celcius)",
                        "Abbreviation": "C"
                    },
                    "AttributeValuesPossible": [
                        {
                            "ID": "138",
                            "Name": "0-10%",
                            "Description": "1-10% Cloud cover"
                        },
                        {
                            "ID": "139",
                            "Name": "11-25%",
                            "Description": "11-25% Cloud cover"
                        },
                        {
                            "ID": "140",
                            "Name": "25-50%",
                            "Description": "25-50% Cloud cover"
                        },
                        {
                            "ID": "141",
                            "Name": "50-75%",
                            "Description": "50-75% Cloud cover"
                        },
                        {
                            "ID": "142",
                            "Name": "76-100%",
                            "Description": "76-100% Cloud cover"
                        }
                    ]
                },
                {
                    "ID": "3505",
                    "AttributeTypeID": "76",
                    "AttributeValueID": null,
                    "ParentFormEntryID": null,
                    "HowSpecified": "2",
                    "OrderNumber": "1",
                    "UnitID": null,
                    "SubplotTypeID": null,
                    "OrganismInfoID": null,
                    "Picklist": null,
                    "AttributeCategoryID": "7",
                    "MinimumValue": "0.0",
                    "MaximumValue": "0.0",
                    "Description": "Precipitation (general) for citizen science observations",
                    "ValueType": "1",
                    "UnitDetails": {
                        "Name": "Unknown",
                        "Abbreviation": null
                    },
                    "AttributeValuesPossible": [
                        {
                            "ID": "143",
                            "Name": "No Rain",
                            "Description": "No rain falling"
                        },
                        {
                            "ID": "144",
                            "Name": "Mist",
                            "Description": "A light mist"
                        },
                        {
                            "ID": "145",
                            "Name": "Light Rainfall",
                            "Description": "Light rainfall"
                        },
                        {
                            "ID": "146",
                            "Name": "Moderate Rainfall",
                            "Description": "Moderate rainfall"
                        },
                        {
                            "ID": "147",
                            "Name": "Heavy Rainfall",
                            "Description": "Heavy Rainfall"
                        }
                    ]
                },
                {
                    "ID": "3506",
                    "AttributeTypeID": "78",
                    "AttributeValueID": null,
                    "ParentFormEntryID": null,
                    "HowSpecified": "2",
                    "OrderNumber": "3",
                    "UnitID": null,
                    "SubplotTypeID": null,
                    "OrganismInfoID": null,
                    "Picklist": null,
                    "AttributeCategoryID": "7",
                    "MinimumValue": "0.0",
                    "MaximumValue": "0.0",
                    "Description": "Specific land cover types needed by citizen science programs",
                    "ValueType": "1",
                    "UnitDetails": {
                        "Name": "Unknown",
                        "Abbreviation": null
                    },
                    "AttributeValuesPossible": [
                        {
                            "ID": "155",
                            "Name": "Spruce Fir Forest and Woodland",
                            "Description": null
                        },
                        {
                            "ID": "156",
                            "Name": "Aspen Forest",
                            "Description": null
                        },
                        {
                            "ID": "157",
                            "Name": "Mixed Aspen and Spruce/Fir Forest",
                            "Description": null
                        },
                        {
                            "ID": "158",
                            "Name": "Montane Meadow",
                            "Description": null
                        },
                        {
                            "ID": "159",
                            "Name": "Subalpine Meadow",
                            "Description": null
                        },
                        {
                            "ID": "160",
                            "Name": "Subalpine Riparian Shrubland",
                            "Description": null
                        },
                        {
                            "ID": "161",
                            "Name": "Alpine Meadow",
                            "Description": null
                        },
                        {
                            "ID": "162",
                            "Name": "Alpine Riparian Shrubland",
                            "Description": null
                        },
                        {
                            "ID": "163",
                            "Name": "Wetland/pond/marsh/lake",
                            "Description": null
                        },
                        {
                            "ID": "164",
                            "Name": "Dry Tundra",
                            "Description": null
                        },
                        {
                            "ID": "178",
                            "Name": "Meadow",
                            "Description": null
                        },
                        {
                            "ID": "179",
                            "Name": "Wetland/Riparian",
                            "Description": null
                        },
                        {
                            "ID": "180",
                            "Name": "Forest",
                            "Description": null
                        },
                        {
                            "ID": "181",
                            "Name": "Alpine Tundra",
                            "Description": null
                        }
                    ]
                },
                {
                    "ID": "3507",
                    "AttributeTypeID": "265",
                    "AttributeValueID": null,
                    "ParentFormEntryID": null,
                    "HowSpecified": "1",
                    "OrderNumber": "5",
                    "UnitID": null,
                    "SubplotTypeID": null,
                    "OrganismInfoID": null,
                    "Picklist": null,
                    "AttributeCategoryID": "7",
                    "MinimumValue": "0.0",
                    "MaximumValue": "0.0",
                    "Description": "BMIs that require high quality water to live",
                    "ValueType": "3",
                    "UnitDetails": {
                        "Name": "Unknown",
                        "Abbreviation": null
                    }
                },
                {
                    "ID": "3512",
                    "AttributeTypeID": null,
                    "AttributeValueID": null,
                    "ParentFormEntryID": null,
                    "HowSpecified": "3",
                    "OrderNumber": null,
                    "UnitID": null,
                    "SubplotTypeID": null,
                    "OrganismInfoID": "213012",
                    "Picklist": null,
                    "AttributeCategoryID": null,
                    "MinimumValue": null,
                    "MaximumValue": null,
                    "Description": null,
                    "OrganismDetails": {
                        "Name": "Aaptos aaptos (Aaptos    )"
                    },
                    "ValueType": null
                },
                {
                    "ID": "3522",
                    "AttributeTypeID": "86",
                    "AttributeValueID": null,
                    "ParentFormEntryID": "3512",
                    "HowSpecified": "1",
                    "OrderNumber": null,
                    "UnitID": null,
                    "SubplotTypeID": null,
                    "OrganismInfoID": null,
                    "Picklist": null,
                    "AttributeCategoryID": "1",
                    "MinimumValue": "0.0",
                    "MaximumValue": "0.0",
                    "Description": "Diameter at Breast Height",
                    "ValueType": "2",
                    "UnitDetails": {
                        "Name": "Miles",
                        "Abbreviation": null
                    }
                },
                {
                    "ID": "3523",
                    "AttributeTypeID": null,
                    "AttributeValueID": null,
                    "ParentFormEntryID": null,
                    "HowSpecified": "3",
                    "OrderNumber": null,
                    "UnitID": null,
                    "SubplotTypeID": null,
                    "OrganismInfoID": "213347",
                    "Picklist": null,
                    "AttributeCategoryID": null,
                    "MinimumValue": null,
                    "MaximumValue": null,
                    "Description": null,
                    "OrganismDetails": {
                        "Name": "Aaptos (Aaptos     )"
                    },
                    "ValueType": null
                },
                {
                    "ID": "3524",
                    "AttributeTypeID": "7",
                    "AttributeValueID": null,
                    "ParentFormEntryID": "3523",
                    "HowSpecified": "2",
                    "OrderNumber": null,
                    "UnitID": null,
                    "SubplotTypeID": null,
                    "OrganismInfoID": null,
                    "Picklist": null,
                    "AttributeCategoryID": "1",
                    "MinimumValue": null,
                    "MaximumValue": null,
                    "Description": null,
                    "ValueType": "1",
                    "UnitDetails": {
                        "Name": "Unknown",
                        "Abbreviation": null
                    },
                    "AttributeValuesPossible": [
                        {
                            "ID": "15",
                            "Name": "Female",
                            "Description": null
                        },
                        {
                            "ID": "16",
                            "Name": "Male",
                            "Description": null
                        },
                        {
                            "ID": "17",
                            "Name": "Asexual",
                            "Description": null
                        },
                        {
                            "ID": "18",
                            "Name": "Hermaphroditic",
                            "Description": null
                        },
                        {
                            "ID": "219",
                            "Name": "Unknown",
                            "Description": "Sex not able to be determined in the field"
                        }
                    ]
                }
            ]
        }
    ]
}