DarcyF1 API (0.3) Documentation

The below describes how you can interact with the DarcyF1 API. In order to use the API, you will need to be provided a set of credentials - please contact admin to discuss your use case.

Authentication

You will be provided with a Key and a Secret to authenticate to the API. Both the Key and the Secret must be included in the request's Headers.

Limits

The API is rate limited. Limits are applied to a session, and the limit is currently 10 requests per second. Requests beyond this limit will be rejected with an HTTP 429 (Too many requests) status code error.

Sending a request

The API accepts a GET request.

The request must contain the authentication Key and the Secret key-value pairs in the headers.

Response

The API will provide a JSON response. A successful API request will always include a status of success and a JSON object named api that includes information about the response itself.

---

Endpoint - video

The video endpoint accepts 1 to 10 video ID numbers and returns information about the video.

https://www.darcyf1.com/api/0.3/video/{videoID}

The videoID is a string containing 1 to 10 integers that are each between 1 and 6 digits long. The integers are separated by a comma (,).

Examples

https://www.darcyf1.com/api/0.3/video/123
https://www.darcyf1.com/api/0.3/video/456,88721,632,99910

Example Response

For each videoID provided, a JSON object will be returned. The data included within this video object will vary depending on the video.

A request of https://www.darcyf1.com/api/0.3/video/2456,88721,632,99910 returns the following response.

[
    {
        "id": "2456",
        "metadata": {
            "category": "GP2",
            "season": "2007",
            "race": "monaco",
            "hosted_by": "darcyf1",
            "commentary": "eng",
            "action_type": "clip",
            "upload_timestamp_utc": 0,
            "uploader_username": "admin",
            "views": "1136",
            "favourited": 0,
            "comments": 1,
            "sensitivity": "none",
            "last_edited": 0
        },
        "media": {
            "video": {
                "url": "https://www.darcyf1.com/videos/gp2/2007/monaco/Monaco07_Rodriguez_Crashes.avi",
                "filesize": 15.98,
                "resolution": {
                    "width": 512,
                    "height": 384
                },
                "codec": {
                    "video": "mpeg4",
                    "audio": "mp3"
                },
                "bitrate": "1620",
                "duration": "00:01:22.7",
                "framerate": 25
            },
            "thumbnail": {
                "featured": "https://www.darcyf1.com/videos/gp2/2007/monaco/thumbs/04.jpg",
                "preview": "https://www.darcyf1.com/videos/gp2/2007/monaco/thumbs/2456.prev.jpg",
                "map": "https://www.darcyf1.com/videos/gp2/2007/monaco/2456.thumbs.vtt"
            },
            "html5": "https://www.darcyf1.com/videos/gp2/2007/monaco/Monaco07_Rodriguez_Crashes.mp4"
        }
    },
    {
        "id": "88721",
        "metadata": {
            "category": "United_SportsCars",
            "season": "2018",
            "race": "Sebring",
            "hosted_by": "youtube",
            "commentary": "zxx",
            "action_type": "clip",
            "upload_timestamp_utc": 1521897093,
            "uploader_username": "vettelisthebest",
            "views": "254",
            "favourited": 0,
            "comments": 1,
            "sensitivity": "none",
            "last_edited": 1521897101
        },
        "media": {
            "video": "",
            "thumbnail": {
                "featured": "https://img.youtube.com/vi/U4Enks0hs8Q/mqdefault.jpg"
            },
            "html5": "https://www.youtube.com/embed/U4Enks0hs8Q?rel=0"
        }
    },
    {
        "id": "99910",
        "metadata": {
            "category": "IndyCar",
            "season": "1997",
            "race": "Mid_Ohio",
            "hosted_by": "darcyf1",
            "commentary": "eng",
            "action_type": "clip",
            "upload_timestamp_utc": 1540469417,
            "uploader_username": "mattia",
            "views": "207",
            "favourited": 0,
            "comments": 0,
            "sensitivity": "none",
            "last_edited": 1582675618
        },
        "media": {
            "video": {
                "url": "https://www.darcyf1.com/videos/indycar/1997/mid_ohio/MidOhio_1997_FP_DeFerran_Crash.mp4",
                "filesize": 1.27,
                "resolution": {
                    "width": 480,
                    "height": 360
                },
                "codec": {
                    "video": "h264",
                    "audio": "aac"
                },
                "bitrate": "508",
                "duration": "00:00:20.9",
                "framerate": 25
            },
            "thumbnail": {
                "featured": "https://www.darcyf1.com/videos/indycar/1997/mid_ohio/thumbs/99910.jpg",
                "preview": "https://www.darcyf1.com/videos/indycar/1997/mid_ohio/thumbs/99910.prev.jpg",
                "map": "https://www.darcyf1.com/videos/indycar/1997/mid_ohio/99910.thumbs.vtt"
            },
            "html5": ""
        }
    },
    {
        "api": {
            "version": "0.3",
			"current": "0.3",
            "time_utc": 1626825277,
            "execution": 111.98
        },
        "status": "success",
        "warnings": [
            "Video ID 632 does not match a video hosted on DarcyF1."
        ]
    }
]

The following table details the keys that can be returned, along with example values.

---

Endpoint - me

The me endpoint provides access to information about the requesting user's profile on DarcyF1.

https://www.darcyf1.com/api/0.3/me/{detail}

The optional detail attribute is a string from the following options, and determines which information is returned.

Examples

https://www.darcyf1.com/api/0.3/me/
https://www.darcyf1.com/api/0.3/me/all
https://www.darcyf1.com/api/0.3/me/cards
https://www.darcyf1.com/api/0.3/me/friends

Example Response

A request of https://www.darcyf1.com/api/0.3/me/all made by the user cardtest2 returns the following response. Note, the cards section has been truncated for brevity.

[
    {
        "username": "cardtest2",
        "status": "active",
        "email": {
            "address": "[email protected]",
            "verified": "Yes"
        },
        "xp": 779,
        "tokens": 252,
        "rank": 4,
        "registration_utc": 1523067180,
        "last_login_utc": 1639517756,
        "last_visit_utc": 1639517995,
        "donations_usd": 0,
        "donator_status": 0,
        "videos": {
            "comments": 0,
            "favourites": 0,
            "uploads": 0,
            "skip_moderation_categories": [
                "No"
            ]
        },
        "friends": 1,
        "invitations": 1,
        "invited_by_user": null,
        "cardspy_trial_status": "active",
        "preferences": {
            "avatar_url": "https://avatars.darcyf1.download/cardtest25436.jpg",
            "paypal_email": "",
            "video_subscriptions": [],
            "profile_activities": [
                "donated",
                "comment"
            ],
            "personal_external_url": "",
            "custom_title": "",
            "block_message_types": [],
            "site_components": {
                "cards": 1,
                "tipping_f1": 0,
                "tipping_v8": 0,
                "thumbhunt": 1,
                "upload_videos": "1"
            },
            "hide_recent_videos": 0,
            "banner": 0,
            "theme": "dark",
            "favourite_card": 0,
            "timezone": "America/Los_Angeles",
            "thumbs_up_message": "Thank you"
        }
    },
    {
        "cards": {
            "sets_completed": [],
            "115219": {
                "serial": "1.1",
                "inverse": 0,
                "collected": {
                    "time_utc": 1560477069,
                    "method": "gift",
                    "from_user": "admin"
                }
            },
			.
			.
			.
			.
			.
            "462155": {
                "serial": "1.10",
                "inverse": 0,
                "collected": {
                    "time_utc": 1598063525,
                    "method": "trade",
                    "from_user": "admin"
                }
            }
        }
    },
    {
        "friends": {
            "admin": {
                "time_utc": 1637040175,
                "level": 4,
                "friendship_points": 581
            }
        }
    },
    {
        "api": {
            "version": "0.3",
            "current": "0.3",
            "time_utc": 1640300469,
            "execution": 504
        },
        "status": "success"
    }
]

The following table details the keys that can be returned, along with example values.

---

API Status

Response included in all API queries

Parent Object	Key	Type	Description	Example Value
null	api	object	Contains information about the API response.
api	version	string	Version of the API providing the response.	0.3
api	version	string	Most current version of the API.	0.3
api	time_utc	integer	The time (UTC) that the API provided the response.	1616455884
api	execution	float	How many milliseconds the API script took to generate a response. Includes two decimal places.	3.92
null	status	string	Identifies whether the API returned any errors. Either success or error	success
null	errors	array of strings	Descriptive text for any error(s) generated while attempting to generate a response. If present, will contain one or more entries. Will only be present if status is error	More than 10 video IDs provided. Limit your request to 10 video IDs.
null	warnings	array of strings	Descriptive text for any warning(s) generated while attempting to generate a response. If present, will contain one or more entries.	Video ID 1234 has been removed from DarcyF1, and replaced by Video ID 5678.

Errors

The API will return a JSON object that includes a key named status that will list a value of either success or error. When an error status is returned, the JSON response will include a key called errors which is an array of string(s) that describe the error(s).

Example

The below is a response to a request that is missing the API Authentication headers.

[
	{
		"errors": [
			"API credentials not supplied."
		],
		"status": "error"
	}
]

PHP + CURL Example

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://www.darcyf1.com/api/0.3/video/2456,88721,632,99910',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Key: redacted',
    'Secret: redacted'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Change Log (from 0.2)

• [{"metadata":{"commentary"}}] - Commentary language is now presented as ISO 639-3 lanugage code instead of a ISO 3166-1-alpha-2 country code.
• [{"metadata":{"uploader_url"}}] - Removed. Static URL can be inferred from [{"metadata":{"uploader"}}]
• [{"metadata":{"last_edited"}}] - Added.
• [{"metadata":{"favourited"}}] - Added.
• [{"metadata":{"comments"}}] - Added.
• [{"metadata":{"credit":{"name"}}}] - Added.
• [{"metadata":{"credit":{"url"}}}] - Added.
• [{"metadata":{"upload_timestamp_utc"}}] - Data type changed to integer.
• [{"metadata":{"views"}}] - Data type changed to integer.
• [{"media":{"video":{"resolution":{"width"}}}}] - Data type changed to integer.
• [{"media":{"video":{"resolution":{"height"}}}}] - Data type changed to integer.
• [{"media":{"video":{"filesize"}}}] - Data type changed to float.
• [{"media":{"video":{"framerate"}}}] - Data type changed to integer.
• [{"media":{"html5"}}] - Will now return as an empty string if there is an unresolved automated error report from our web player. Once staff have marked the issue resolved, this key will return its usual value.
• [{"errors"}] - New error condition added when none of the video IDs provided match a video hosted on DarcyF1. If some videos match and others don't, a warning will be returned.
• [{"warnings"}] - A new array of strings which will return any issues that don't prevent the API from responding successfully but may be providing unexpected data.
• [{"warnings"}] - A new warning added for each video ID provided that does not match a video hosted on DarcyF1.
• [{"warnings"}] - A new warning added for when a video has been replaced on DarcyF1 (typically with a better version). Note this warning also the following attribute.
• [{"replacedBy"}] - Added video ID of new video when requested video has been replaced on DarcyF1.
• me - Endpoint added.