Back to top

SciStarter API

SciStarter provides free tools to:

Only projects that are 1) registered on SciStarter and 2) use the Participation API and Visible Confirmation Message are eligible for inclusion in special, curated programming with the Girl Scouts, Discover, PBS, Nature, schools, universities, libraries, and other partnerships where evidence and analytics are needed to award badges, credits, and recognition.

First, create a SciStarter account and register your project on SciStarter:

https://scistarter.com/add

(If you have an inventory of projects to upload, you can ​do a bulk upload of projects here: https://scistarter.com/api#add​)

Our editors will review your project and either email you with questions or approve and publish your project. You’ll hear from us either way. Once your project is published, sign in and go to your project page on SciStarter. Click the “Tools” tab on the top navigation where you will find your Project ID Code. You’ll need this later.

Now, it’s time to use the Participation API & Visible Confirmation Message:

Gold Standard: The highest level of integration, based on security, ease of use by citizen scientists, and data accuracy.

  1. Get your API key. You'll be asked to log in (if you're not already) before accessing your personal API key, since it's associated with your SciStarter account.
  2. Integrate with OAuth 2 to use SciStarter as an authorization server. Before you can use OAuth 2, you must contact SciStarter to obtain an OAuth Client ID. Our authorization request endpoint is https://scistarter.com/authorize and our access token endpoint is https://scistarter.com/token?key=YOUR-API-KEY
  3. Embed the Visible Confirmation Message on your site
  4. Retrieve a profile ID for each participant to affiliate their contributions with their SciStarter profile (pick one​ of the following)
  5. Record events to participant profiles

Silver Standard: Use the Participation API and Visible Confirmation Message without OAuth ​as​ the next best thing. It’s secure and produces high quality, validated data.

  1. Get your API key. You'll be asked to log in (if you're not already) before accessing your personal API key, since it's associated with your SciStarter account.
  2. Embed the Visible Confirmation Message on your site
  3. Retrieve a profile ID for each participant to affiliate their contributions with their SciStarter profile (pick one​ of the following)
  4. Record events to participant profiles

Retrieving a user's profile §

The next step of integration is to retrieve a profile number. There are several ways of retrieving a profile number as described on this page and in more detail on your project page dashboard (click "Tools" from the top navigation bar on your project page on SciStarter).

Option 1: by hashed email address

We immediately hash the emails sent to us through option 2, and discard the plaintext, but if you're more comfortable or legally required to, you can hash the email yourself and send us only the hash digest. We won't have any idea what the email address actually is, unless it belongs to somebody who has explicitly given us permission to know.

All calls to this endpoint succeed, whether the hash matches a SciStarter member or not. If the hash doesn't match, we have no idea who the person actually is, but if they later join SciStarter, we are able to maintain the same profile id for them, and so it does not matter whether they sign up for SciStarter before or after your project; either way, the user experience is the same.

We delete data sent to us regarding profiles that are not known SciStarter members. Anonymous profiles only exist to smooth out the user experience when people join a project, and then join SciStarter later.

To use this feature, you need to use the SHA256 hash function, and send us the hex-encoded digest.

GET https://scistarter.com/api/profile/id?hashed=HEX(SHA256(email address))&key=API key

Example: Retrieving a profile number by email address (Python 2.7)

from json import loads
from urllib2 import urlopen
from contextlib import closing
from hashlib import sha256
with closing(urlopen('https://scistarter.com/api/profile/id?hashed={}&key=kjsdfh8fsao48u3...'.format(sha256('example%40example.com').hexdigest()))) as f:
  data = loads(f.read())
		

Result: Dictionary containing the profile number

{"scistarter_profile_id": 42006, "result": "success", "known": true}
        
Option 2: by email address

Using a user's email address is the simpler way to get their profile number. Using the email address and your API key, you can retrieve the ID in a single GET request. We only store a hash of the email, unless it belongs to one of our registered users.

GET https://scistarter.com/api/profile/id?identifier=email address&key=API key

Example: Retrieving a profile number by email address (Python 2.7)

from json import loads
from urllib2 import urlopen
from contextlib import closing
with closing(urlopen('https://scistarter.com/api/profile/id?identifier=example%40example.com&key=kjsdfh8fsao48u3...')) as f:
  data = loads(f.read())
		

Result: Dictionary containing the profile number

{"scistarter_profile_id": 42006, "result": "success", "known": true}
        
Option 3: after OAuth 2 authorization

You can also use OAuth 2 to retrieve the ID. For help setting up OAuth integration with your site, please contact us directly at info@scistarter.com.

This method requires the user to explicitly authorize you, which means they must create a SciStarter account if they don't have one already. Once a user has authorized you via OAuth, you can retrieve that user's profile number with a single additional request. We recommend that you store it rather than going through the process of retrieving it multiple times.

GET https://scistarter.com/api/user_info (requires Authorization header)

Example: Retrieving a profile number after OAuth authorization (Python 2.7)

from json import loads
from urllib2 import urlopen, Request
from contextlib import closing
with closing(urlopen(Request('https://scistarter.com/api/user_info', headers = {'Authorization': 'Bearer [OAuth token]'})) as f:
  data = loads(f.read())
		

Result: Dictionary containing the profile number and some other information

{"profile_id": 42006,
 "user_id": [SciStarter user ID],
 "url": '[URL of the user's SciStarter page]',
 "result": "success"}
        

Recording a user activity event to a user's profile §

POST https://scistarter.com/api/record_event?key=API key

We highly recommend performing this request asynchronously, in a worker thread or by some other asynchronous mechanism. There is no need for your site to wait for the result of this call before proceeding with processing the user's interactions.

In addition to the API key as a GET parameter, the POST body must contain at least the following items:

profile_id
The user's profile number, as retrieved above
project_id
Your project's SciStarter id number. ​Once your project is added to SciStarter, sign in and go to your dashboard and select your project page on SciStarter. Click the “Tools” tab on the top navigation where you will find your ​Project ID #​.
type
What did the participant actually do? One of classification (Classification / Transcription), collection (Data collection), signup (Joined the project)

There are also several optional fields you can provide in order to better identify the user activity:

where
GeoJSON or WKT encoding of the geographic point where the activity occurred
when
The time at which the activity occurred, in ISO yyyy-mm-ddThh:mm:ss format (note the T separating date and time). UTC times preferred.
duration
The duration of the activity, in seconds, in integer or real number format.
magnitude
Integer representing how valuable this particular contribution was, as defined by you
extra
Any additional data you want to attach to the event. JSON recommended. Limited to 64k

Example: Recording a data collection event (Python 2.7)

from json import loads
from urllib2 import urlopen
from contextlib import closing
with closing(urlopen(
      'https://scistarter.com/api/record_event?key=kjsdfh8fsao48u3...',
      'profile_id=42006&project_id=1979&type=collection'
    )) as f:
  data = loads(f.read())
		

Result: Dictionary indicating success or error

{"event_id": [This event's unique id], "result": "success"}
        

That's it for the Participation API and Visible Confirmation Message!

SciStarter provides other APIs and resources to help more people discover and join citizen science projects §

Help people find citizen science projects by embedding the SciStarter Project Finder Widget on your site. Search for projects in SciStarter by topic, phrase, url, activity, or region Find metadata about a project. Add projects from your database to SciStarter.

Embed a SciStarter widget §

Use our widget builder to generate your widget and embed code. The example shown here is a widget for a single project with a header.

If you have existing widgets, you can edit them by following these links:

Help people find citizen science projects by embedding the SciStarter Project Finder Widget on your site. Search for projects in SciStarter by topic, phrase, url, activity, or region Find metadata about a project. Add projects from your database to SciStarter.

Retrieving the current list of topics and activities §

GET https://scistarter.com/finder/metadata

Example: Retrieving current topics and activities (Python 2.7)

from json import loads
from urllib2 import urlopen
from contextlib import closing

with closing(urlopen('https://scistarter.com/finder/metadata')) as f:
  data = loads(f.read())
		  

Result: Dictionary of topic and activity data

{u'topics':
  [{u'name':
        u'Space',
    u'description':
        u'Extra-atmospheric'},
    ...
  ],
u'activities':
  [{u'name':
        u'At the Beach',
    u'description':
        u'Things to do at the beach'}, ...
  ]
}
		  

GET https://scistarter.com/finder?format=json&key=API key&q=search term

Instead of q, which is a very broad search, you can combine the following search parameters:

  • phrase
  • topic
  • activity
  • url
  • lat - latitude in decimal degrees (lng must be provided as well)
  • lng - longitude in decimal degrees (lat must be provided as well)
  • UN - either the name or code of a UN geographical region, to limit the search to projects explicitly in that region (if a project does not specify a UN region, it will be excluded)
  • jsonp - If you want the result in JSONP instead of plain JSON, set this parameter to the callback name.

Example: Retrieving projects about butterflies (Python 2.7)

from json import loads
from urllib2 import urlopen
from contextlib import closing

with closing(urlopen('https://scistarter.com/finder?format=json&key=kjsdfh8fsao48u3...&q=butterfly')) as f:
data = loads(f.read())
				

Result: Dictionary of butterfly-related projects

{u'results':
  [{u'id':
      899,
    u'title':
      u'LepiMAP',
    ...
   },
   {u'id':
      822,
    u'title':
      u'Michigan Butterfly Network',
    ...
   }, ...
				

Example: Retrieving space projects that contain the word 'amateur' (Python 2.7)

from json import loads
from urllib2 import urlopen
from contextlib import closing

with closing(urlopen('https://scistarter.com/finder?format=json&key=kjsdfh8fsao48u3...&topic=space&phrase=amateur')) as f:

  data = loads(f.read())
				

Result: Dictionary of amateur space projects

{u'results':
  [{u'id':
       917,
    u'title':
       u'Independent Generation of Research',
    ...
   },
   {u'id':
       871,
    u'title':
       u'Slooh',
    ...
   }, ...
				

Retrieving project data in JSON §

GET https://scistarter.com/api/project/project-id?key=API key

Example: Retrieving the LepiMAP project (Python 2.7)

from json import loads
from urllib2 import urlopen
from contextlib import closing
with closing(urlopen('https://scistarter.com/api/project/899?key=kjsdfh8fsao48u3...')) as f:
  data = loads(f.read())
				

Result: Dictionary of project fields

{u'activities':
  [u'While fishing',
   u'On a hike',
   u'At home',
   u'On a walk, run',
   u'At school',
   u'At night'],
u'description':
   u"LepiMAP is the African butterfly and moth mapping project. LepiMAP is a joint project of the...",
u'tags':
   [u'africa',
    u'biodiversity',
    u'butterflies',
    u'butterfly',
    u'conservation',
    u'lepidoptera',
    u'mapping',
    u'moths',
    u'science'],
u'title':
   u'LepiMAP',
u'topics':
   u'Nature & Outdoors',
   u'Animals',
   u'Ecology & Environment',
   u'Education',
   u'Biology'],
u'url': u'https://scistarter.com/project/899-LepiMAP'
u'UN_regions': [{u'code': u'001', u'name': u'World'},
               {u'code': u'019', u'name': u'Americas'},
               {u'code': u'021', u'name': u'Northern America'}],
u'regions': [
   { # LepiMAP has no region, so this is just to show the structure
       u'name': u'LepiMAP region',
       u'osm_id': 0,   # Open Street Map ID, if we have one available
       u'legal': u'',  # Legal terms that apply to the geometry, if different from SciStarter TOS
       u'geometry': {} # GeoJSON formatted geomtetry information
   }
]}
				

Adding a project to SciStarter §

POST https://scistarter.com/api/project/add/

Optionally, ?jsonp=callback may be appended to the url.

After being successfully added, projects must pass an editorial review (usually less than 24 hours) before being published on SciStarter

The POST body must be an object in JSON format, and must contain "key": "your API key" among its fields. The rest of the fields should be PPSR fields and values, or fields and values from the following list.

name
The project name (required, unless the PPSR equivalent is used; a string)
scistarter_id
If included, this allows you to update the record for a previously added project. The same API key must be used to update the project as was originally used to add it.
description
A description of the project (required, unless the PPSR equivalent is used; a string; one to three paragraphs suggested)
url
The URL of the project's primary web page (required, unless the PPSR equivalent is used; a string)
origin
A string identifying the organization adding these data to SciStarter (required, unless the PPSR equivalent is used; a short string)
contact_name
The name of the person SciStarter should contact about this project (a string)
contact_affiliation
The name of the contact person's organization (a string)
contact_email
The contact person's email address (required, unless the PPSR equivalent is used; a string)
contact_phone
The contact person's phone number (a string)
contact_address
The contact person's mailing address (a string)
presenting_org
The organization sponsoring or presenting the project to the public (a string)
rsvp
The email address or URL to which to participants should RSVP, if applicable
address
The street address where this project or event takes place, if applicable
city
The city where this project or event takes place, if applicable
state
The state, province, or administrative region where this project or event takes place, if applicable
zip
The zip or postal code where this project or event takes place, if applicable
country
The country where this project or event takes place, if applicable
video_url
The URL of the project's introductory video (a string)
blog_url
The URL of the project's blog (a string)
twitter_name
The Twitter handle of the project (a string)
facebook_page
The URL of the project's Facebook page (a string)
status
One of 'starting', 'active', 'hiatus', 'complete', 'hidden'
preregistration
Use SciStarter's preregistration feature (boolean, default false)
goal
A short description (64 characters or less recommended, 120 max) of what the project hopes to accomplish (a string)
task
A short description (64 characters or less recommended, 120 max) of what the participant will do to help the project (a string)
image
The URL where SciStarter may fetch a project logo or introductory image (a string)
image_credit
The proper way to credit the image (a string)
how_to_join
Instructions to help willing participants begin to participate (a string)
special_skills
Particular skills or training that are needed to participate (a string)
gear
Special equipment that is needed before a person can participate (a string)
outdoors
Whether project participation takes place outside (boolean, default true)
indoors
Whether project participation takes place inside (boolean, default true)
time_commitment
A plain-language description of how much time will be asked of participants (a string)
project_type
Either 'Project' or 'Event' (default 'Project')
audience
A list containing one or more of 'Adults', 'College', 'Elementary school (6 - 10 years)', 'Families', 'Graduate Students', 'High school (14 - 17 years)', 'Middle school (11 - 13 years)'
regions
A GeoJSON polygon or multipolygon representing the area of coverage for participating in this project, or a string containing either the word online or anywhere to indicate a project with online participation or global participation, respectively.
region_label
A short plain language description of the region or regions (a string; optional)
UN_regions
A list of UN geographical region names or {code: "FOO", name: "BAR"} pairs