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.

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 [email protected].

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 classification (Classification / Transcription), collection (Data collection)

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"}
        

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())
		  

{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'}, ...
  ]
}
		  

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())
				

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

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())
				

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

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())
				

{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
   }
]}