The following API endpoints are intended for light/recreational use. Please do not abuse them. The intended audience for these endpoints is anyone doing light/hobbyist development.

The API.Toys website is hosted on a Lightspeed server and resides behind CloudFlare. You should not receive a cached response to queries, but should results seem repetitive, append your query with a unique value like a Unix timestamp.

If any calls begin returning a "deprecated" element, then this indicates an endpoint is reaching end-of-life and should be reviewed. Click here for more information.

/api/iso_3166-1

The iso_3166-1 endpoint returns ISO-standard Country information. By default calling the endpoint will return an array of Country objects containing respective Alpha-2,Alpha-3,Numeric codes and English (short) country names.

Specifying a code as a parameter will get an object of countries by the requested code type.

Please take special care to note that an object is returned when requesting a specific code type. Returning objects allows you to easily iterate to a specific code.

Valid codes are: alpha-2,alpha-3,numeric

[{alpha2: "AF",alpha3: "AFG",numeric: "004",name: {eng: "Afghanistan"}},{alpha2: "AX",alpha3: "ALA",numeric: "248",name: {eng: "Aland Islands"}}]

Optional Parameters:

Name Type Method Example
want String MVC/Get/Post iso_3166-1/alpha-2
iso_3166-1?want=numeric

/api/iso_639

The iso_639 endpoint returns ISO-standard Language information. By default calling the endpoint will return an array of Language objects containing respective ISO-639-1,ISO-639-2/T,ISO-639-2/B,ISO-639-3, ISO Language name (in English), localised language name (to the origin country), and language family group.

Specifying a code as a parameter will get an object of languages by the requested code type.

Please take special care to note that an object is returned when requesting a specific code type. Returning objects allows you to easily iterate to a specific code.

Valid codes are: 1,2t,2b,3

[{"iso_639_1":"aa", "iso_639_2t":"aar", "iso_639_2b":"aar", "iso_639_3":"aar", "iso_name":"Afar", "language_family":"Afro-Asiatic", "name_local":"Afaraf"}]

Optional Parameters:

Name Type Method Example
want String MVC/Get/Post iso_639/1
iso_639?want=2b

/api/dialing_codes

This endpoint returns dialing codes for countries. By default calling the endpoint will return an array of objects containing the dialing code and the English label for a country.

Specifying an ISO 3166 code as a parameter will get an object of dialing codes by the requested ISO code type.

Please take special care to note that an object is returned when requesting a specific code type. Returning objects allows you to easily iterate to a specific country.

Valid codes are: alpha-2,alpha-3,numeric

[{"dialcode":"1", "label":"United States"}, {"dialcode":"93", "label":"Afghanistan"}, {"dialcode":"355", "label":"Albania"}]

Optional Parameters:

Name Type Method Example
want String MVC/Get/Post dialing_codes/alpha-2
dialing_codes?want=numeric

/api/mimetypes

A simple API endpoint that returns an array of objects defining MIME types and extensions, along with an English label of the file type.
[{"label":"3GP", "mime":"video/3gpp", "ext":"3gp"}, {"label":"7-Zip", "mime":"application/x-7z-compressed", "ext":"7z"}]

/api/timestamp

Returns the current UNIX time in seconds. If the microseconds switch is passed, you also get the microseconds as a STRING.

The microseconds are returned as a string in order to provide the full 8 decimal precision and prevent rounding.

{"timestamp":1480520000}
{"timestamp":1480520000,"microseconds":"0.18521000"}

Optional Parameters:

Name Type Method Example
microseconds Boolean MVC/Get/Post timestamp/true
timestamp?microseconds=true

/api/timezone_offset

Returns the current time in a given timezone (in seconds), the offset from UTC (in seconds), and the timezone name.

The 'zone' parameter must be an ISO abbrevation for a timezone. Read this Wiki article for the abbreviations list.

Please note that microseconds are returned as a string in order to provide the full 8 decimal precision and prevent rounding.

{"result":1480520000,"offset":0,"name":"UTC"}
{"result":1480502000,"offset":-18000,"name":"America%2FNew_York"}

Required Parameters:

Name Type Method Example
zone String MVC/Get/Post timezone_offset/EST
timezone_offset?zone=CET
timezone_offset?zone=CET&microseconds=true

Optional Parameters:

Name Type Method Example
microseconds Boolean MVC/Get/Post timezone_offset/EST/true
timezone_offset?zone=CET&microseconds=true

/api/coin_flip

Simple API call that flips a virtual coin. Returns 'heads' or 'tails'.
{"result":"heads"}

/api/dice_roll

A Dice roller. Default's to a d6x1 (1 six-sided dice).
{"dice":"d6","rolls":[3]}
{"dice":"d10","rolls":[7,4]}

Optional Parameters:

Name Type Method Example
sides Integer MVC/Get/Post dice_roll/10
dice_roll?sides=20
dice_roll?sides=8&rolls=2
rolls Integer MVC/Get/Post dice_roll/6/5
dice_roll?rolls=10
dice_roll?sides=8&rolls=2

/api/unix_y2k

A countdown timer to the Unix 32-bit clock reset (Unix's equivalent of the Y2k bug). This API call returns the seconds until the 11 digit Unix timestamp format hits the overflow limit of a 32bit Integer field.

The y2k bug brought us prisoners being released early, which was probably the worst 'disaster' related to Y2k. But what will happen with the Integers overflow at 3:14am on January 19th, 2038 (UTC)? Be. Afraid.

{"maximum_value_of_int32":2147483647,"current_time":1480520000,"seconds_left_before_y2k":666963647}

/api/random_blog_name

Randomly assembles a name that could be used for usernames or blog names.

The paramters "long" and "longer" make slightly longer names using one or more words.

The words list is filtered to remove any words that may sound innapropriate or offensive when combined with other words. If you enable "nsfw", those excluded words are added back into the dictionary, which may result in nsfw phrases.

Some words are just filth. If you want to allow words that are unquestionably adult in nature, enable the "adult" flag.

{"long":false,"longer":false,"nsfw":false,"adult":false,"chosen":"Breezy Drum","more":["Alert Science","Adaptable River","Dull Charles","Repulsive Turtle","Soft Majestic","Bored Warlock","Curious Joe","Long Goose","Hot Wolf","Massive Smith"]}

Optional Parameters:

Name Type Method Example
long Boolean MVC/Get/Post random_blog_name/true
random_blog_name?long=true
random_blog_name?long=true&adult=true
longer Boolean MVC/Get/Post random_blog_name/true/true
random_blog_name?long=true&longer=true
random_blog_name?long=true&longer=true&adult=true
nsfw Boolean MVC/Get/Post random_blog_name/true/false/true
random_blog_name?nsfw=true
random_blog_name?long=true&longer=true&nsfw=true
adult Boolean MVC/Get/Post random_blog_name/true/false/true/true
random_blog_name?adult=true
random_blog_name?long=true&nsfw=true&adult=true

/api/albhed_english

Translates the video game Final Fantasy X's "Al Bhed" language to English.

The 'language' is simple letter swapping on English words. It is actually possible to pronounce and converse in the language.

See the English to Al Bhed endpoint (/api/english_albhed), to reverse the translation.

{"input":"Rammu Funmt","result":"Hello World"}

Required Parameters:

Name Type Method Example
text String Get/Post albhed_english?text=Rammu+Funmt

/api/english_albhed

Translates English to the video game Final Fantasy X's "Al Bhed" language.

See the Al Bhed to English endpoint (/api/albhed_english), to reverse the translation.

{"input":"Hello World","result":"Rammu Funmt"}

Required Parameters:

Name Type Method Example
text String Get/Post english_albhed?text=Hello+World

/api/shift_text

Shifts the characters in the given English 'text' String by a 'num' number of places.

'IBM' shifted -1 places becomes 'HAL'.

If you shift a letter and the position moves beyond the boundary of the 26 letters in the English Alphabet, the alphabet will cycle.

In this scenario 'Zoo' shifted +6 places becomes 'Fuu'

{"input":"IBM","result":"HAL"}

Required Parameters:

Name Type Method Example
text String Get/Post shift_text?text=Hello+World&num=2
num Integer Get/Post shift_text?text=Hello+World&num=2

/api/shift_hash

Shifts the characters in the given English 'text' String by a number of places generated from the provided 32byte hexadecimal hash (an md5 without hyphens is perfect for this).

Works in a similar way to other shifting endpoints like /api/shift_text.

The hash parameter is optional - if you don't provide it, one will be generated for you. The hash used to shift the text will be returned in the response for you to use again.

{input: "Hello World",result: "Zwddg Ogjdv",hash: "dc143797d478251e9eb468d8d43bf056"}

Required Parameters:

Name Type Method Example
text String Get/Post shift_hash?text=Hello+World

Optional Parameters:

Name Type Method Example
hash String (32byte hex/or md5) Get/Post shift_hash?text=Hello+World&hash=f4da9e9daa5841dc475214631bb228c3

/api/shift_qwerty

Shifts the characters in the given English 'text' String by a 'num' number of places.

Functionally identical to /api/shift_text however this uses the English QWERTY keyboard map for letter positioning.

'IBM' shifted -1 places becomes 'UVN'.

The shift pattern moves your submitted text left or right on the keyboard. When the letter moves past the end of the line it goes to the next line down or up the keyboard depending on usage of positive or negative numbers. The key map loops if you go out of range (either end of the keyboard).

In this scenario 'Zoo' shifted +7 places becomes 'Qhh'

{"input":"IBM","result":"UVN"}

Required Parameters:

Name Type Method Example
text String Get/Post shift_qwerty?text=Hello+World&num=2
num Integer Get/Post shift_qwerty?text=Hello+World&num=2

/api/rock_paper_scissors

Provides an endpoint that will either randomly give a Rock Paper Scissors move, or if you provide a move the endpoint responds with a play and result.

The parameter 'guess' is optional, and must be one of : 'rock', 'paper' or 'scissors'

{"cpu": "scissors", "player": "", "winner": ""}
{"cpu": "scissors", "player": "rock", "winner": "player", "move": "rock crushes scissors"}

Optional Parameters:

Name Type Method Example
guess String MVC/Get/Post rock_paper_scissors/rock
rock_paper_scissors?guess=paper

/api/rock_paper_scissors_lizard_spock

An extended version of the 'Rock, Paper, Scissors' endpoint that plays 'Rock, Paper, Scissors, Lizard, Spock', a popular enhancement to the traditional game.

The parameter 'guess' is optional, and must be one of : 'rock', 'paper', 'scissors', 'lizard' or 'spock'

{"cpu": "spock", "player": "", "winner": ""}
{"cpu": "lizard", "player": "rock", "winner": "player", "move": "rock crushes lizard"}

Optional Parameters:

Name Type Method Example
guess String MVC/Get/Post rock_paper_scissors_lizard_spock/spock
rock_paper_scissors_lizard_spock?guess=lizard

/api/random_syllables

Generates a phrase made out of random syllables.

The parameter 'words' returns x number of words.

Results are URL Encoded

{"words":["Yoxvem-bux","Dah%27fem","Taj","Hib+Nub+Yurrpaplugg+Xth","Sot+Saltte","Wehqol-gogg","Kojduggfov","Moff+Gou+Panrth","Hufffip%27tohxac","Dux+Nip+Yth"]}

Optional Parameters:

Name Type Method Example
words Integer MVC/Get/Post random_syllables/5
random_syllables?words=20

/api/soap_plot_generator

Creates ficticious plot summaries that could be used as a writing basis for Television Soap Operas/Serials.

All parameters accepted only through POST.

If you do not supply any of the following optional parameters, the endpoint will use a built-in default set of data to complete your query.

{"plots": {"plot1": "Jason and Shona run away together.", "plot2": "Mark impregnates Emily.", "plot3": "An old friend of Emily appears."}}

Optional Parameters:

Name Type Method Description
child_male String Post CSV list of male child characters.
child_female String Post CSV list of female child characters.
teen_male String Post CSV list of teen male characters.
teen_female String Post CSV list of teen female characters.
adult_male String Post CSV list of adult male characters.
adult_female String Post CSV list of adult female characters.
elderly_male String Post CSV list of elderly male characters.
elderly_female String Post CSV list of elderly female characters.
events String Post CSV list of life/story events. eg: Wedding,Funeral,Interview
circumstances String Post CSV list of life/story circumstances. eg: Gas Leak,Medical Operation,Car Accident,Flash Flood
objects String Post CSV list of life/story objects. eg: a cigarette,a lighter,a computer

/api/nato_phonetic

Returns the phrase "text" passed as a GET or POST parameter in the NATO alphabet.
{"text": "Hello World","words": ["Hotel","Echo","Lima","Lima","Oscar","Whiskey","Oscar","Romeo","Lima","Delta"], "out": "Hotel Echo Lima Lima Oscar Whiskey Oscar Romeo Lima Delta"}

Optional Parameters:

Name Type Method Example
text String Get/Post nato_phonetic?text=Hello+World

/api/worm_name

Returns 1 or more random names from the Worms video-game series.

The minimum number to return is 1, and must always be specified with MVC parameters.

The 'language' parameter currently accepts "en-gb" for English or "cs-cz" for Czech and defaults to English if not specified.

{results: ["Penguin"]}
{results: ["Chatchie","Andrea","Roger","Sheridan","Burnt"]}

Optional Parameters:

Name Type Method Example
num Integer MVC/Get/Post worm_name/5
worm_name/5/en-gb
worm_name?num=5
worm_name?num=1&language=en-gb
language String MVC/Get/Post worm_name/1/en-gb
worm_name?num=1&language=en-gb

/api/medieval_name

Returns 1 or more random medieval English names.

"group" has the following accepted values: "celtic", "norman_germanic", "norse", "saxon", "rare" and "all". The "all" group includes data from all groups.

"gender" can be "male" or "female".

"surname" enables the additional return of a surname with the first name. Please note that Surname only works with the "all" grouping currently.

String values in the response are URL Encoded.

{results: ["Segarus"]}
{results: ["Eddusa+de+Malhortye","Alfreda+Roard","Goldgeve+Rou"]}

Required Parameters:

Name Type Method Example
num Integer MVC/Get/Post medieval_name/5
medieval_name/5/all
medieval_name?num=5
medieval_name?num=1&group=all
group String MVC/Get/Post medieval_name/1/all
medieval_name?num=1&group=all
gender String MVC/Get/Post medieval_name/1/all//male
medieval_name?num=1&group=all&gender=male
surname String MVC/Get/Post medieval_name/1/all/male/true
medieval_name?num=1&group=all&gender=male&surname=true

/api/gw2_character

Returns a randomly generated Guild Wars 2 Character Profile. This information can be used to create a new character in the game.

"species" accepts any valid playable species. Values: "human", "charr", "asura", "norn", "sylvari".

"gender" accepts "male" or "female".

"class" accepts any valid playable class eg: "warrior", "guardian", "revenant", "engineer", "thief", "ranger", "mesmer", "necromancer" or "elementalist".

Names for Human and Norn species are not returned by this endpoint. Use in combination with /api/medieval_name for Human and Norn names.

String values in the response are URL Encoded.

MVC parameters require the correct order of species/gender/class. Use "null" for when you don't want to send species of gender.

{"species":"norn","gender":"female","age":41,"class":"revenant","professions":["Weaponsmith","Jeweler","Leatherworker","Scribe"],"body":{"height":"Average","shape":"Skinny"},"starting_gear":"resplendent curtain","personality":"dignity","personal_story":{"stage1":"protect the spirits","stage2":"blacked out","stage3":"snow leopard"},"order":"vigil"}

Optional Parameters:

Name Type Method Example
species String MVC/Get/Post gw2_character/human
gw2_character/norn/female
gw2_character?species=human
gw2_character?species=asura&gender=male
gender String MVC/Get/Post gw2_character/human/male
gw2_character?species=sylvari&gender=male
class String MVC/Get/Post gw2_character/human/male/warrior
gw2_character?species=sylvari&gender=female&class=engineer

/api/ip_address

Returns the IP Address of the caller. This will return in whatever format (v4 or v6) that the server receives your request in.

{"ip":"1.2.3.4"}

/api/hostname

Returns the hostname of the IP address your request is made with.

{"hostname":"host1234.myserver.com"}

/api/user_agent

Returns the user agent string of the client.

{"user_agent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64)"}

/api/whoami

Returns IP Address, User Agent and the Hostname of the request.

{"ip":"1.2.3.4","hostname":"host1234.myserver.com","user_agent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64)"}

/api/countdown_anagram

Returns either an 8 or 9 letter anagram (depending on parameter usage) from the UK Television show 'Countdown'.

Nine letter anagrams are taken from the final round 'Countdown Conundrums' at the end of the programme.

Eight letter anagrams are from the 'Teatime teaser' section of the show, used as puzzles for the viewers at home to solve during commercial breaks.

An eight letter anagram may also return an additional "clue" element to provide a hint at what the correct solution is. Hints are not available for nine letter puzzles.

If no size parameter is specified in the call, the endpoint will default to the 9-letter anagrams.

The "answers" element of the response is returned as an array in case there are multiple possible acceptable answers for a conundrum.

Along with "anagram" and "answers", you may also get "rejected_answers" and "reasons" returned (both latter elements are optional).

The "rejected_answers" is an array containing unacceptable answers, and "reasons" contains the reason for each rejection.

{"anagram":"TONGVICAR", "answers":["CAVORTING"]}
{"anagram":"CHICNURSE","answers":["CRUNCHIES"],"rejected_answers":["SCRUNCHIE"],"reasons":["'Scrunchie' is a brand name."]}

Required Parameters:

Name Type Method Example
size Integer MVC/Get/Post countdown_anagram/8
countdown_anagram?size=9

/api/find_words

An endpoint that will return a list of possible English words from a String of nine letters.

Please note: This is a slow endpoint and caching is implemented.

The server will scan a dictionary for possible combinations and the response can take up to 60 seconds to respond.

With an emphasis on speed, not all words may return in the response due to the algorithm passing over the dictionary aiming for a balance of speed and thoroughness.

The returned words range from four to nine letters long.

{"letters":["G","Y","H","D","N","O","E","U","R"],"sorted":"DEGHNORUY","found":["GREYHOUND","YOURN","YOUR","YOUNGER","ROUGHY","HUNGRY","HYDROGEN","HORNY","ENROUGH","ROUGHEN","HURON","ROHUN","OURN","ROUN"]}

Required Parameters:

Name Type Method Example
text String MVC/Get/Post find_words/GYHDNOEUR
find_words?text=GYHDNOEUR

/api/check_dictionary

Returns TRUE or FALSE if the word provided is found within an English dictionary and is suitable for board games that exclude brand names, place or people's names.

Accepts text only via GET or POST.

This endpoint is intended for word games like Scrabble or Countdown and is limited to a maximum length of 9 characters.

{"found": true}

Required Parameters:

Name Type Method Example
text String Get/Post check_dictionary?text=greyhound

/api/solve_sum

Returns if it is possible to solve a maths problem with given numbers and a target. Similar to the Numbers round in the Countdown Television Show.

Provide anywhere from 5 to 10 numbers in CSV format as the 'values' parameter.

Provide a 'target' number (any value between 1 and 999).

If a solution is possible that reaches the 'target', the endpoint will provide the equation.

{"values": "25,10,6,40,4,1", "target": "641", "calculation": "(((25*6)*4)+1)+40"}

Required Parameters:

Name Type Method Example
values CSV String Get/Post solve_sum?values=25,10,6,40,4,1&target=641
target Integer Get/Post solve_sum?values=25,10,6,40,4,1&target=641

/api/penguin_joke

A simple endpoint that returns a random joke from a database of McVitie's Penguin jokes.

{"q":"Why can't Penguins fly?","a":"Because they are chocolate biscuits"}

/api/barcode

Attempts to generate a barcode resource for given input.

Accepted Barcode types are: "aztec","codablockf","code128","code16k","code39e","code49","code93","codeone","datamatrix","dotcode","gridmatrix","hanxin","micropdf417","microqrcode","pdf417","qrcode","telepen","upnqr"

Content can be any valid String for the barcode type you select. Limited quality checking is performed on input values, so you need to do your own content validation. Errors in input will result in failure to generate a barcode.

{"input":"Test data","type":"qrcode","output":"http://api.toys/tmp/barcodes/f737432585f6e3ed41a5fb0596f37900.png"}

Required Parameters:

Name Type Method Example
code String MVC/Get/Post barcode/qrcode
barcode?code=code16k
content String Post

Deprecation of Endpoints

If any endpoints in the Basic API are marked for retirement, you will begin to see a "deprecated" data element returned on queries. This data element will contain more information on the deprecation which will help you as a developer take action.

The date of removal will normally be included, and possibly a suggestion on alternative calls that could be made to achieve the same information.

Example:

{"old_response_data":"Just some old data here.","deprecated":"This endpoint will be switched off on 2019-01-01. Use /api/new_request_endpoint instead."}

It is a very good idea to design your application to warn you if you begin to see "deprecated" data responses from any API call you consume.