semarainc / Turnitin-API

An unofficial REST API for Turnitin.com.

Turnitin API

An unofficial REST API for Turnitin.com.

Built by Ronak Badhe / Kento Nishi

Endpoints

All endpoints are relative to https://turnitin-api.herokuapp.com. Use HTTPS to protect your credentials.

/login

• Method: POST
• Payload:

  {
      email: "[e-mail]",
      password: "password"
  }

• Response:

  {
      auth: {/* authentication object */}
  }

/courses

• Method: POST
• Payload:

  {
      auth: {/* authentication object */}
  }

• Response:

  [
      {
          title: "Course Name",
          url: "Course URL"
      },
      /* array of courses */
  ]

/assignments

• Method: POST
• Payload:

  {
      auth: {/* authentication object */},
      course: {/* course object */}
  }

• Response:

  [
      {
          title: "Assignment Title",
          dates: {
              due: "%m/%d/%Y %H:%M:%S",
              post: "%m/%d/%Y %H:%M:%S",
              start: "%m/%d/%Y %H:%M:%S"
          },
          info: "Assignment Info",
          submission: "Submission Title",
          aid: "assignment-id",
          oid: "outbox-id"
      },
      /* array of assignments */
  ]

/download

• Method: POST
• Payload:

  {
      auth: {/*authentication object */},
      assignment: {/* assignment object */},
      pdf: false // PDF or original submission format
  }

• Response: Raw File Bytes

/submit

• Method: POST
• Form Data:

  {
      auth: "authorization object",
      assignment: "assignment object",
      title: "Submission Title",
      filename: "FileName.format",
      userfile: undefined // submission file
  }

  The /submit endpoint accepts form data, not JSON.

• Response:

  {
      file_name: "File Name",
      file_size: "File Size",
      page_count: 0, // page count
      word_count: 0, // word count
      char_count: 0, // character count
      image_url_stub: "Paper Image Render URL",
      status: 1, // 0 = error, 1 = OK
      uuid: "Submission ID"
  }

Examples

Python 3

import json
import requests

url = "https://turnitin-api.herokuapp.com"

USERNAME = "[e-mail]"
PASSWORD = "password"


with requests.Session() as s:
    login_result = s.post(url + "/login", json={
        "email": USERNAME,
        "password": PASSWORD
    })
    auth = login_result.json()

    courses_result = s.post(url + "/courses", json=auth)
    courses = courses_result.json()
    for c in courses:
        if "World Lit" in c["title"]:
            world_lit = c
    print(world_lit)

    first_course_data = dict(**auth, course=world_lit)
    assignments_result = s.post(url + "/assignments", json=first_course_data)
    assignments = assignments_result.json()
    print(assignments[0])

    download_query = dict(**auth, assignment=assignments[0], pdf=True)
    r = s.post(url + '/download', json=download_query)
    print(f"Status code {r.status_code}")
    with open("test_download.pdf", 'wb+') as fout:
        fout.write(r.content)

    # Example case - submit to the fourth assignment 
    with open("Document.docx", 'rb') as uf:
        # We must convert the json to a string to submit in a form
        submit_query = dict(
            auth=json.dumps(auth["auth"]),
            assignment=json.dumps(assignments[3]),
            title="test submission 1",
            filename="Document.docx"
        )
        r = s.post(url + "/submit", data=submit_query, files={"userfile": uf})
    print(r.json())

Additional Information

• The API may fail to collect information about your courses and assignments if there are more than 25 items. To mitigate this issue, increase the Items per page setting in your Turnitin User Info panel.