Back to top

SciStarter API

SciStarter provides free tools to:

  • Help participants track and earn credit for their contributions to projects; (see Participation API and Visible Snippet)
  • Help project leaders amplify projects, recruit more participants, and learn more about participants' experiences and interests while advancing scientific research; (see Participation API and Visible Snippet)
  • Help organizations including Girl Scouts USA, Discover, PBS, school districts, college campuses, libraries and others share projects from SciStarter with their communities and acquire evidence needed to award badges, credits, and recognition; (see Participation API and Visible Snippet)
  • Help researchers learn more about the motivations, behaviors, and learning outcomes of participants; (see Participation API and Visible Snippet)
  • Help anyone add citizen science to their websites through an embeddable project finder widget; (see Project Finder Widget)

Only projects that are 1) registered on SciStarter and 2) use the Participation API and Visible Snippet 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 Snippet:

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 Snippet 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 Snippet 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 Snippet 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

Bronze Standard: Use the Visible Snippet ​with Telemetry for use without the Participation API. ​Like the Visible Snippet used with the Participation API, this version will display a message to the participant that their contributions can be added to their SciStarter dashboard (and /or allows them to easily join SciStarter without leaving your site), but it also actively records contributions and affiliates them with the participant’s ID.​ ​T​his is still good but it’s not as great as the Gold or Silver Standards ​because it uses a participant’s browser to validate contributions, so if more than one person uses the same computer or phone to contribute to your project (which is likely in schools and libraries, for example), ​unless each person has their own sign-in on the device (or at least signs in to ​SciStarter before contributing), contributions can be incorrectly attributed to the last person who did sign in.

  1. Copy your Project ID # from your project’s “tools” tab on SciStarter. You’ll find this on your project page.
  2. Embed the Visible Snippet with Telemetry on your site
Finally, access advanced analytics about your project and participants on your project page:
  • Visit your project page on SciStarter.
  • Click the “Stats” tab on the top navigation.
  • Then, click any of the links on the left to see what other projects your participants are joining, contributing to, or bookmarking.
  • Click “volunteer stats” and messages to see details and communicate with participants

Email info@scistarter.com with any questions

Embedding the visible snippet §

Without Telemetry

If you are using the gold or silver standard, you must include this version of the visible snippet HTML code on a data submission confirmation page (a page on your site where participants have just shared observational data, annotated files, or participated in your project in other ways). ​This snippet displays a visible message and is required and important because we value transparency and this visible message helps a participant easily opt in or out of affiliating their contributions with their existing or new SciStarter dashboard. It also enables a participant to join SciStarter ​without leaving your site.

<script data-mode="passive" src="https://scistarter.com/static/api/recordevent_with_scistarter_inline_signup.js"></script>

If our SciStarter styling on the widget is too jarring in contrast to your own site's styling, you can use this instead:

<script data-mode="passive" src="https://scistarter.com/static/api/recordevent_local_styles.js"></script>

With Telemetry

If you are using the bronze standard, you need to enable telemetry from the visible snippet, or you won't gain any of the benefits of affiliation with SciStarter. To use the Visible Snippet with Telemetry, fill in your project ID number and select the participation type, then use the snippet embed code that appears below.





<script data-project_id="" src="https://scistarter.com/static/api/recordevent_with_scistarter_inline_signup.js"/></script>

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.

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"}
        
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"}
        
Option 3: via the user's web browser

You can add a <script> tag your pages which fills in a form field with the user's profile number. When the form is submitted, the profile number is there among the rest of your data.

Note: Using this method to retrieve the profile number allows malicious users to falsely attribute their contributions to a different user's profile.

<script data-profile="CSS selector for the target form field" src="https://scistarter.com/static/api/apihelper.js"></script>

Example: Retrieving a profile number into a form field

<form method="post">
  <input type="hidden" name="profile_id" value="">
  <input type="text" name="data">
  <input type="submit" value="Record my data">
</form>
<script data-profile="input[name='profile_id']" src="https://scistarter.com/static/api/apihelper.js"></script>
		
Option 4: 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 Snippet!

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'
preregistration
Use SciStarter's preregistration feature (boolean, default false)
goal
A short description of what the project hopes to accomplish (a string)
task
A short description 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