NAV Navbar
Y
javascript python shell

Introduction

This page describes the YouNoodle API. Our API provides you access to live data from competitions that run on our platform, allowing you to build dashboards, internal tools and maybe even things that we at YouNoodle would not have have anticipated.

We provide client libraries in JavaScript and Python, but you may also write your own bindings in your programming language of choice using our REST-like HTTP/JSON API. You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

All API endpoints are available behind https://www.younoodle.com/client-api/v1/.

Client libraries

Our client libraries are available as younoodle on npm and PyPI.

Install as follows:

npm i --save younoodle

pip install younoodle

Authentication

In order to use the YouNoodle API, you will need an API key. Please ask a member of the YouNoodle staff for help in obtaining an API key.

To authorize, use this code:

const YouNoodle = require('younoodle')({apiKey: 'honey_badger'});

import younoodle

api = younoodle.authorize('honey_badger')

curl https://www.younoodle.com/client-api/v1/competition/my_competition \
    -H 'YouNoodle-API-Key: 56f9bbec9bc614e351e5eea2ea851e31'            \
    -H 'Accept: application/json'

When you have retrieved your API key, you may authenticate yourself using our client libraries as shown to the right.

If you are directly interacting with our HTTP endpoints, you can authenticate yourself at either by passing your key in an HTTP header called YouNoodle-API-Key or by appending the key as the get parameter api_key to your query (for example: /competitions?api_key=honey_badger).

Make sure to replace honey_badger with your API key.

API keys are valid for one year, after which they can be renewed by contacting staff.

Competitions

Get Your Competition

Each API key is linked to exactly one competition. You will need your competition identifier to do anything useful with the API – it acts as your username. This is the slug written in lowercase letters and underscores in place of spaces that shows up in your browser’s address bar when you navigate to your competition.

import younoodle

api = younoodle.authorize('honey_badger')
api.Competition.get('my_competition')

const YouNoodle = require('younoodle')({apiKey: 'honey_badger'});

const competition = YouNoodle.getCompetition('my_competition');

curl https://www.younoodle.com/client-api/v1/competition/my_competition \
    -H 'YouNoodle-API-Key: 56f9bbec9bc614e351e5eea2ea851e31'            \
    -H 'Accept: application/json'

The above command returns JSON structured like this:

{
  "id": "the_honey_badger_challenge",
  "object": "competition",
  "name": "The Honey Badger Challenge"
  "created_at": 1459530776,
  "facebook_handle": "honeybadger123",
  "twitter_handle": "honeybadger123",
  "logo_url": "https://static.younoodle.com/pictures/ab/cd/ef/honeybadger.jpg"
}

This endpoint retrieves all kittens.

HTTP Request

GET https://younoodle.com/client-api/v1/competition/<id>

URL Parameters

Parameter Description
id Your competition identifier

Get all entry rounds belonging to a competition

import younoodle

api = younoodle.authorize('honey_badger')
api.EntryRounds.get('my_competition')

const YouNoodle = require('younoodle')({apiKey: 'honey_badger'});

const entryRounds = YouNoodle.getEntryRounds('my_competition');

curl https://www.younoodle.com/client-api/v1/competition/my_competition/entry-rounds \
    -H 'YouNoodle-API-Key: 56f9bbec9bc614e351e5eea2ea851e31'                         \
    -H 'Accept: application/json'

The above command returns JSON structured like this:

{
    "object" => "list",
    "count" => 2,
    "page" => 1,
    "has_more" => false,
    "data" => [
        {
            "id": "the_honey_badger_challenge_1",
            "object": "entry_round",
            "url": "/client-api/v1/competition/the_honey_badger_challenge/entry-rounds/the_honey_badger_challenge_1",
            "name": "The Honey Badger Challenge 1",
            "is_open": false,
            "deadline_at": 1459555199,
            "judge_rounds": "url": "/client-api/v1/competition/the_honey_badger_challenge/entry-rounds/the_honey_badger_challenge_1/judge-rounds",
            "entries": "url": "/client-api/v1/competition/the_honey_badger_challenge/entry-rounds/the_honey_badger_challenge_1/entries",
            "entries_created": 2203,
            "entries_submitted": 1445
        },
        {
            "id": "the_honey_badger_challenge_2",
            "object": "entry_round",
            "url": "/client-api/v1/competition/the_honey_badger_challenge/entry-rounds/the_honey_badger_challenge_2",
            "name": "The Honey Badger Challenge 2",
            "is_open": true,
            "deadline_at": 1459545234,
            "judge_rounds": "url": "/client-api/v1/competition/the_honey_badger_challenge/entry-rounds/the_honey_badger_challenge_2/judge-rounds",
            "entries": "url": "/client-api/v1/competition/the_honey_badger_challenge/entry-rounds/the_honey_badger_challenge_2/entries",
            "entries_created": 503,
            "entries_submitted": 401
        }
    ]
}

Your competition will have one or more entry rounds associated with it. These can be accessed with the following endpoint.

HTTP Request

GET http://local.younoodle.com:8000/client-api/v1/competition/<id>/entry-rounds

URL Parameters

Parameter Description
id Your competition identifier

Query parameters

Add ?page=n as a request parameter to page through the data.

Get all judge rounds of an entry round

Each entry round has one or more judge rounds. This endpoint retrieves a list of all judge rounds belonging to the given entry round.

import younoodle

api = younoodle.authorize('honey_badger')
api.JudgeRounds.get('my_competition')

const YouNoodle = require('younoodle')({apiKey: 'honey_badger'});

const judgeRounds = YouNoodle.getJudgeRounds('my_competition', 'my_entry_round');

curl https://www.younoodle.com/client-api/v1/competition/my_competition/entry-rounds/my_entry_round/judge-rounds \
    -H 'YouNoodle-API-Key: 56f9bbec9bc614e351e5eea2ea851e31'                                                     \
    -H 'Accept: application/json'

The above command returns JSON structured like this:

{
    "object" => "list",
    "count" => 2,
    "page" => 1,
    "has_more" => false,
    "data": [
        {
            "id": "honey_badger_judging_1",
            "object": "judge_round",
            "url": "/client-api/v1/competition/the_honey_badger_challenge/entry-rounds/the_honey_badger_challenge_1/judge-rounds/honey_badger_judging_1",
            "name": "Honey Badger Judge Round 1",
            "deadline_at": 1364428799,
            "entries": "/client-api/v1/competition/the_honey_badger_challenge/judge-rounds/honey_badger_judging_1/entries",
            "number_of_entries": 234,
            "entries_judged": 200,
            "judging_progress": 0.85
        },
        {
            "id": "honey_badger_judging_2",
            "object": "judge_round",
            "url": "/client-api/v1/competition/the_honey_badger_challenge/entry-rounds/the_honey_badger_challenge_1/judge-rounds/honey_badger_judging_2",
            "name": "Honey Badger Judge Round 2",
            "deadline_at": 1364458463,
            "entries": "/client-api/v1/competition/the_honey_badger_challenge/judge-rounds/honey_badger_judging_2/entries",
            "number_of_entries": 453,
            "entries_judged": 100,
            "judging_progress": 0.22
        }
    ]
}

HTTP Request

GET http://local.younoodle.com:8000/client-api/v1/competition/<id>/entry-rounds/<entry-round-id>

URL Parameters

Parameter Description
id Your competition identifier
entry-round-id The entry round identifier whose judge rounds you want to access

Query parameters

Add ?page=n as a request parameter to page through the data.

Get all entries in an entry round

This endpoint gives you access to all entries in a given entry round, in pages of 100.

import younoodle

api = younoodle.authorize('honey_badger')
api.EntriesInEntryRound.get('my_competition', 'my_competition')

const YouNoodle = require('younoodle')({apiKey: 'honey_badger'});

const entries = YouNoodle.getEntresInEntryRound('my_competition', 'my_entry_round');

curl https://www.younoodle.com/client-api/v1/competition/my_competition/entry-rounds/my_entry_round/entries \
    -H 'YouNoodle-API-Key: 56f9bbec9bc614e351e5eea2ea851e31'                                                \
    -H 'Accept: application/json'

The above command returns JSON structured like this:

{
    "object": "list",
    "count": 2,
    "page": 1,
    "has_more": false,
    "data": [
        {
            "id": "6942526137426e743069797a42543172",
            "object": "entry",
            "url": "/client-api/v1/competition/entry-rounds/the_honey_badger_challenge/entries",
            "name": "A marvellous entry",
            "created_at": 1459530831,
            "submitted_at": 1476717797
        },
        {
            "id": "4c4131613947423338766d6d61716c35",
            "object": "entry",
            "url": "/client-api/v1/competition/entry-rounds/the_honey_badger_challenge/entries",
            "name": "A revolutionary entry",
            "created_at": 1459535852,
            "submitted_at": 1459930831
        }
    ]
}

HTTP Request

GET http://local.younoodle.com:8000/client-api/v1/competition/<id>/entry-rounds/<entry-round-id>/entries

Query parameters

Add ?page=n as a request parameter to page through the data.

URL Parameters

Parameter Description
id Your competition identifier
entry-round-id The entry round identifier whose entries you want to access

Get all entry data in an entry round

This endpoint gives you access to all entry form data in a given entry round, in pages of 100. Note that at the moment we only provide access to form data entered by the team as a whole, not to personal form data or recommender form data.

import younoodle

api = younoodle.authorize('honey_badger')
api.EntryDataInEntryRound.get('my_competition', 'my_competition')

const YouNoodle = require('younoodle')({apiKey: 'honey_badger'});

const entries = YouNoodle.getEntresInEntryRound('my_competition', 'my_entry_round');

curl https://www.younoodle.com/client-api/v1/competition/my_competition/entry-rounds/my_entry_round/entries/data \
    -H 'YouNoodle-API-Key: 56f9bbec9bc614e351e5eea2ea851e31'                                                \
    -H 'Accept: application/json'

The above command returns JSON structured like this:

{
    "object": "list",
    "count": 2,
    "page": 1,
    "has_more": false,
    "data": [
        {
            "id": "6942526137426e743069797a42543172",
            "object": "entry",
            "url": "/client-api/v1/competition/entry-rounds/the_honey_badger_challenge/entries",
            "name": "A marvellous entry",
            "created_at": 1459530831,
            "submitted_at": 1476717797,
            "form_data" => [
                {
                    "field_id": 15727,
                    "question": "Full name",
                    "type": "text",
                    "text": "The Honey Badger Startup"
                },
                {
                    "field_id": 15729,
                    "question": "Category",
                    "type": "option",
                    "selected_option": "Cryptocurrencies"
                }
            ]
        },
        {
            "id": "4c4131613947423338766d6d61716c35",
            "object": "entry",
            "url": "/client-api/v1/competition/entry-rounds/the_honey_badger_challenge/entries",
            "name": "A revolutionary entry",
            "created_at": 1459535852,
            "submitted_at": 1459930831,
            "form_data" => []
        }
    ]
}

HTTP Request

GET http://local.younoodle.com:8000/client-api/v1/competition/<id>/entry-rounds/<entry-round-id>/entries/data

Query parameters

Add ?page=n as a request parameter to page through the data.

URL Parameters

Parameter Description
id Your competition identifier
entry-round-id The entry round identifier whose entry data you want to access

Get all entries in a judge round

This endpoint gives you access to all entries in a given judge round, in pages of 100.

import younoodle

api = younoodle.authorize('honey_badger')
api.EntresInJudgeRound.get('my_competition')

const YouNoodle = require('younoodle')({apiKey: 'honey_badger'});

const entries = YouNoodle.getEntresInJudgeRound('my_competition', 'my_entry_round');

curl https://www.younoodle.com/client-api/v1/competition/my_competition/judge-rounds/my_judge_round/entries \
    -H 'YouNoodle-API-Key: 56f9bbec9bc614e351e5eea2ea851e31'                                                \
    -H 'Accept: application/json'

The above command returns JSON structured like this:

{
    "object" => "list",
    "count" => 2,
    "page" => 1
    "has_more" => false,
    "data": [
        {
            "id": 53256,
            "object": "judge_round_entry",
            "url": "/client-api/v1/competition/the_honey_badger_challenge/judge-rounds/honey_badger_judging_1/entries",
            "name": "An entry",
            "created_at": 1364399716,
            "identifier": "4fe593ad58408b9efb4070e04ffce44c",
            "submitted_at": 0,
            "final_score": 0,
            "judging_progress": 0,
            "track": "Aerospace"
        },
        {
            "id": 53257,
            "object": "judge_round_entry",
            "url": "/client-api/v1/competition/the_honey_badger_challenge/judge-rounds/honey_badger_judging_1/entries",
            "name": "Another entry",
            "created_at": 1364399717,
            "identifier": "4fe593ad58408b9efb4070e04ffce44d",
            "submitted_at": 1364399716,
            "final_score": 0.5,
            "judging_progress": 1,
            "track": "IoT"
        }
    ]
}

HTTP Request

GET http://local.younoodle.com:8000/client-api/v1/competition/<id>/judge-rounds/<judge-round-id>/entries

Query parameters

Add ?page=n as a request parameter to page through the data.

URL Parameters

Parameter Description
id Your competition identifier
judge-round-id The judge round identifier whose entries you want to access

Errors

The YouNoodle API uses the following error codes:

Error Code Meaning
400 Bad Request – Your request is malformed
401 Unauthorized – Your API key is invalid
405 Method Not Allowed – You tried to access a resource with an invalid HTTP method
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarily offline for maintenance. Please try again later.
javascript python shell