SciStarter API

You can use the SciStarter APIs to let your participants track and gain credit for their contributions. Or, add some citizen science to your site by embedding the SciStarter widget. Learn more about each of the API tools and goals below.

Back to top
Help your participants track and earn credit for their contributions by using the Participation API & Snippet. 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. You will need to get your personal API key to use several of the available APIs.

To retrieve a user's profile ID §

SciStarter's tools make it easy for citizen scientists to find and join projects. By integrating our easy-to-use, secure, free tools, project owners can help citizen scientists track (and earn credit for) their contributions across projects and platforms! In doing so, project owners gain otherwise inaccessible insights about their participants, including an understanding of what other projects they're doing, how frequently they participate in projects, etc. Integrating with our tools unlocks access to SciStarter's free, optional volunteer management functions and enhanced analytics.

Using the API to record events is a little more involved than using the snippet (which is described on your project's tools page), but it allows us to authenticate the reported events, which means the data are more valuable for scientific purposes, and can be used to grant more meaningful rewards to participant.

The first step of integration is to retrieve a profile ID. There are three ways of retrieving a profile ID. After retrieving the profile ID, you must include this visible HTML code on a data submission confirmation page (a page on your site where participants share observational data, annotate files, or participate in your project in other ways). <script data-mode="passive" src="https://scistarter.com/static/api/recordevent_with_scistarter_inline_signup.js"></script>

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.

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 id 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 ID

{"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 ID. 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 id 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 ID

{"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 id. When the form is submitted, the profile id is there among the rest of your data.

Note: Using this method to retrieve the profile id 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 id 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 ID 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 id 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 ID and some other information

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

To record a user activity event to a user's profile §

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

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 id, as retrieved above
project_id
Your project's SciStarter id number, which is the number just before your project's name in the project page URL on SciStarter

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

type
What did the user actually do? One of question (Asked a question), classification (Classification / Transcription), collection (Data collection), signup (Joined the project), blog (Posted a blog), group (Started a group), event (Started an event), project (Started a project), resource (Submitted a resource)
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"}
        

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:

To retrieve 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',
    ...
   }, ...
				

To retrieve 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
   }
]}
				

To add 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)
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)
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)
origin
A string identifying the organization adding these data to SciStarter (a short string)
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

Getting 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.