API Methods
Example URL: http://api.flashcardexchange.com/v1/search?q=math&api_key=CuGEqR171v&indent=4&sort=bestmatch&limit=100&offset=100&user_id=183373092
The search method will return a list of flashcard sets that match the given search phrase. It will return an array of card set data. Use the card_set_id value from each card set to retrieve the flashcards for that card set using the get_card_set method. The search phrase should follow the search phrase rules. Searching for phrases, excluding terms, grouping and boolean searches are supported.

Input Parameters

Parameter Required Description
api_key yes Your application key.
indent no An option parameter specifing the number of spaces to use for indenting and returning formatted JSON data. This parameter should be ommitted in production environments.
q yes The tag we are searching for. The search phrase should follow the search phrase rules.
sort no Currently supported values for the sort parameter are "bestmatch" "popularity" and "mostrecent". "bestmatch" is the default value. The sort parameter is a string and should match these values exactly.
user_id no Use this parameter to filter results for a specific user_id. If the user_id matches the user_id of the authenticated user then private data will be included in the search. Alternatively you can use the search modifier user:user_name described in the search phrase rules. If you sent user_id as a query parameter the user: search filter will be ignored.
limit no The number of records that will be returned. The default value for this parameter is 100. The max value is 200.
offset no The record offset. Use this value for pagination. If 1000 records are return and you have the limit set to 100 then you want to set the offset parameter to 100 to view page 2 of the search results.

search Output Example

{
  "response_type": "ok", 
  "results": {
    "meta": {
        "total_found": "57576", 
        "total": "1000"
    },
    "sets": [
        {
            "description": "genetics test 3", 
            "card_set_id": 1985483, 
            "title": "Genetics test 3", 
            "tags": "genetics", 
            "save_count": 0, 
            "creation_date": "2011-11-15", 
            "author": "thejosh11", 
            "author_id": 357561, 
            "flashcard_count": 55
        }, 
        {
            "description": "Leib and Pelzer\nLiver\nLA Esophageal Disease\nRumen/Abomasum Disorders", 
            "card_set_id": 1985485, 
            "title": "3rd year - GI Test 3", 
            "tags": "2013 gastroenterology vmrcvm", 
            "save_count": 0, 
            "creation_date": "2011-11-15", 
            "author": "nmcclai13", 
            "author_id": 693193, 
            "flashcard_count": 0
        } 
    ]
  }, 
  "parameters": {
    "q": "test", 
    "sort": "mostrecent", 
    "api_key": "CuGEqR171v", 
    "indent": "2"
  }

search meta field Descriptions:

Field Description
total The total size of the recordset returned for the search. This number will never be greater than 1000. Use this value to get a page count for pagination.
total_found Total number of records found for the search. This number can be greater than meta['total'] if meta['total'] is 1000.

search sets field Descriptions:

Field Description
card_set_id card_set_id is the unique identifire for this group of flashcards. Use it in get_card_set to get the JSON document containing the actual flashcards.
creation_date The creation date for this group of flashcards.
description The card set description as set by the author.
title The card set title
tags Space separated list of tags for this card set. Can be used to perform other searches using get_tag.
author_id The unique identified for the creator of these flashcards. Use with get_user to get a data set of other flashcards created by this user.
author The username associated with author_id
flashcard_count The number of flashcards in the card set.
saved_count The number of times this card set has been "saved" to a user's favorite list by someone on the website. Can be used as an indication of popularity.
get_tag
Example URL: http://api.flashcardexchange.com/v1/get_tag?tag=math&api_key=CuGEqR171v&page=1&indent=2&sort=date
get_tag will return a list of all the flashcard sets that have been tagged with a given keyword. Use this method like a single word search. It will return an array of card set data. Use the card_set_id value from each card set to retrieve the flashcards for that card set using the get_card_set method.

Input Parameters

Parameter Required Description
tag yes The tag we are searching for.
api_key yes Your application key.
indent no An option parameter specifing the number of spaces to use for indenting and returning formatted JSON data. This parameter should be ommitted in production environments.
page no This method will return 200 records at a time. If you get 200 records there might be more! Add an integer page parameter to get the next page of data. The default value is 1 so this parameter is not required.
sort no By default card sets returned by this method will be sorted by popularity (save_count). If this parameter exists and the value sent by the parameter is date (the GET parameter would look like this: sort=date) then the card sets will be sorted in descending order by the creation date, showing the most recent additions. Card sets with less than 5 flashcards will not be shown.

get_tag Field Descriptions

Field Description
card_set_id card_set_id is the unique identifire for this group of flashcards. Use it in get_card_set to get the JSON document containing the actual flashcards.
creation_date The creation date for this group of flashcards.
description The card set description as set by the author.
title The card set title
tags Space separated list of tags for this card set. Can be used to perform other searches using get_tag.
author_id The unique identified for the creator of these flashcards. Use with get_user to get a data set of other flashcards created by this user.
author The username associated with author_id
flashcard_count The number of flashcards in the card set.
saved_count The number of times this card set has been "saved" to a user's favorite list by someone on the website. Can be used as an indication of popularity.

get_tag Output Example

{
  "response_type": "ok", 
  "results": {
    "sets": [
      {
        "card_set_id": 204901, 
        "creation_date": "2002-09-23", 
        "description": "twos", 
        "title": "Twos", 
        "tags": "facts math", 
        "author_id": 17605, 
        "author": "swinkie7", 
        "flashcard_count": 20, 
        "save_count": 0
      }, 
      {
        "card_set_id": 614958, 
        "creation_date": "2008-05-05", 
        "description": "GMAT MATH", 
        "title": "GMAT Geometry Areas, Volumes, Perimeter", 
        "tags": "gmat math", 
        "author_id": 350501, 
        "author": "shikella11", 
        "flashcard_count": 35, 
        "save_count": 1
      }
    ]
  }, 
  "parameters": {
    "tag": "math", 
    "api_key": "CuGEqR171v", 
    "indent": "2", 
    "page": "1"
  }
get_card_set
Example URL: http://api.flashcardexchange.com/v1/get_card_set?card_set_id=939976&indent=2&api_key=CuGEqR171v
get_card_set will return a list of all the flashcards that have a given card_set_id. Use this method like a single word search. It will return an array of flashcard data. If the card set requested is a private card set and you are not sending your oauth credentials you will get error 20, meaning you need to authenticate your user. See the oauth documentation. Once authenticated, the user must be the creator of the card set to access a private card set.

Input Parameters

Parameter Required Description
card_set_id yes The id of the card set you want. This can be found in one of the set elements from get_tag or get_user
api_key yes Your application key.
indent no An option parameter specifing the number of spaces to use for indenting and returning formatted JSON data. This parameter should be ommitted in production environments.

Card Set Field Descriptions

Field Description
card_set_id card_set_id is the unique identifire for this group of flashcards. Use it in get_card_set to get the JSON document containing the actual flashcards.
creation_date The creation date for this group of flashcards.
description The card set description as set by the author.
title The card set title
tags Space separated list of tags for this card set. Can be used to perform other searches using get_tag.
author_id The unique identified for the creator of these flashcards. Use with get_user to get a data set of other flashcards created by this user.
author The username associated with author_id
flashcard_count The number of flashcards in the card set.
saved_count The number of times this card set has been "saved" to a user's favorite list by someone on the website. Can be used as an indication of popularity.
flashcards An array of flashcard data elements. Field descriptions for the flashcard elements is below

Flashcard Field Descriptions

Field Description
card_id The unique identifier for this flashcard.
question The textual data for the "question" side of this flashcard.
question_media_type The media type key for any media associated with the question. A value of 2 in this field means there is an associated image. A value of 3 indicates there is an associated mp3 file. All other values (1 or null) means that there is only text.
question_image_url The url for the question image, if any.
question_image_thumbnail_url The url for the question image thumbnail, if any.
question_audio_url The url for the question mp3 file, if any.
answer Textual data for the "answer" side of this flashcard.
answer_media_type The media type key for any media associated with the answer. A value of 2 in this field means there is an associated image. A value of 3 indicates there is an associated mp3 file. All other values (1 or null) means that there is only text.
answer_image_url The url for the answer image, if any.
answer_image_thumbnail_url The url for the answer image thumbnail, if any.
answer_audio_url The url for the answer mp3 file, if any.
display_order Float. Sort on this field to put the flashcards in the order intended by the flashcard author.
modified Timestamp. The last time this flashcard was modified.
side_three Textual data associated with the note/hint/side 3 of the flashcard.

get_card_set Output Example

{
  "response_type": "ok", 
  "results": {
    "card_set_id": 248187, 
    "flashcard_count": 23, 
    "description": "blah", 
    "title": "testing arabic", 
    "tags": "test", 
    "author_id": 18732, 
    "author": "jch", 
    "creation_date": "2004-06-28",
    "flashcards": [
      {
        "answer_media_type": null, 
        "answer_image_url": "http://www.flashcardexchange.com/cardimages/answers/0/1/1210885.jpg", 
        "question_media_type": null, 
        "side_three": "", 
        "question": "other (fem.) t", 
        "question_audio_url": "http://www.flashcardexchange.com/audio/questions/1210885.mp3", 
        "modified": "2005-02-21 20:29:29.577354-08:00", 
        "question_image_thumbnail_url": "http://www.flashcardexchange.com/cardimages/questions/thumbnails/0/1/1210885.jpg", 
        "answer_audio_url": "http://www.flashcardexchange.com/audio/answers/1210885.mp3", 
        "display_order": 1.0, 
        "card_id": 1210885, 
        "answer": "\u0623\u064f\u062e\u0652\u0631\u0649", 
        "answer_image_thumbnail_url": "http://www.flashcardexchange.com/cardimages/answers/thumbnails/0/1/1210885.jpg", 
        "question_image_url": "http://www.flashcardexchange.com/cardimages/questions/0/1/1210885.jpg"
      }, 
      {
        "answer_media_type": null, 
        "answer_image_url": "http://www.flashcardexchange.com/cardimages/answers/0/1/1210886.jpg", 
        "question_media_type": null, 
        "side_three": "", 
        "question": "Jordan", 
        "question_audio_url": "http://www.flashcardexchange.com/audio/questions/1210886.mp3", 
        "modified": "None", 
        "question_image_thumbnail_url": "http://www.flashcardexchange.com/cardimages/questions/thumbnails/0/1/1210886.jpg", 
        "answer_audio_url": "http://www.flashcardexchange.com/audio/answers/1210886.mp3", 
        "display_order": 2.0, 
        "card_id": 1210886, 
        "answer": "\u0627\u0644\u0623\u064f\u0631\u062f\u0646", 
        "answer_image_thumbnail_url": "http://www.flashcardexchange.com/cardimages/answers/thumbnails/0/1/1210886.jpg", 
        "question_image_url": "http://www.flashcardexchange.com/cardimages/questions/0/1/1210886.jpg"
      }
    ] 
  }, 
  "parameters": {
    "card_set_id": "248187", 
    "api_key": "CuGEqR171v", 
    "indent": "2"
  }
}
get_user
Example URL: http://api.flashcardexchange.com/v1/get_user?user_id=183373092&indent=2&api_key=CuGEqR171v&dataset=1
get_user will return an array of card sets created by a given user.

Input Parameters

Parameter Required Description
api_key yes Your application key.
user_id no The id of the user. This can be found in one of the set elements from get_tag or get_card_set. Either this parameter or user_login are required for this method.
user_login no The flashcardexchange.com login of the user. This is usually their email address (some older accounts have something other than an email address but 99% of all users use an email address to log in) Either this parameter or user_id are required for this method.
dataset no Integer. This parameter adjusts the dataset that is returned. A value of 1 (the default value if this parameter is absent) will return card sets that the user created. A value of 2 will return a list of card sets that have been "saved" by this user. Saved sets are like bookmarks the user has made for their favorite sets that were created by others. Users can make modifications to saved sets and they can become variants of the original card set. A value of 3 will return both saved and created card sets, mixed together.
private no a string representation of a boolean value: "true" or "false". If set to "true" a users private card sets will be included. See the oauth documentation for obtaining access to private data.
indent no An option parameter specifing the number of spaces to use for indenting and returning formatted JSON data. This parameter should be ommitted in production environments.

Card Set Field Descriptions

Field Description
card_set_id card_set_id is the unique identifire for this group of flashcards. Use it in get_card_set to get the JSON document containing the actual flashcards.
creation_date The creation date for this group of flashcards.
description The card set description as set by the author.
title The card set title
tags Space separated list of tags for this card set. Can be used to perform other searches using get_tag.
author_id The unique identified for the creator of these flashcards. Use with get_user to get a data set of other flashcards created by this user.
author The username associated with author_id
flashcard_count The number of flashcards in the card set.
saved_count The number of times this card set has been "saved" to a user's favorite list by someone on the website. Can be used as an indication of popularity.
original_card_set_id If the card set is a saved set, this is the id of the original card set from which it was derived.

get_user Output Example

{
  "response_type": "ok", 
  "results": {
    "sets": [
      {
        "card_set_id": 9393939976, 
        "creation_date": "2009-12-07", 
        "description": "this", 
        "title": "blah", 
        "tags": "test", 
        "save_count": 0, 
        "author_id": 18732, 
        "author": "jch", 
        "original_card_set_id": null, 
        "flashcard_count": 11
      }, 
      {
        "card_set_id": 2493039731, 
        "creation_date": "2004-08-08", 
        "description": "This card set was automatically created as part of an update to the card file system.", 
        "title": "Card File Update", 
        "tags": "test", 
        "save_count": 0, 
        "author_id": 18732, 
        "author": "jch", 
        "original_card_set_id": null, 
        "flashcard_count": 56
      }
  }, 
  "parameters": {
    "dataset": "1", 
    "user_id": "1897302", 
    "api_key": "CuGEqR171v",
    "indent": "2"
  }
get_user_data
Example URL: http://api.flashcardexchange.com/v1/get_user_data?api_key=CuGEqR171v&indent=4
get_user_data will return information on the current user who has been authenticated with the oauth procedure. Use this method to get the user_id for use in making additional api calls.

Input Parameters

Parameter Required Description
api_key yes Your application key.
indent no An option parameter specifing the number of spaces to use for indenting and returning formatted JSON data. This parameter should be ommitted in production environments.

User Data Field Descriptions

Field Description
first_name Users first name.
last_name Users last name.
user_id User ID. Use with get_user.
user_display_name What is displayed on the website in lieu of an email address.
email_address The users email address. Usually their log in.

get_user_data Output Example

{
    "response_type": "ok", 
    "parameters": 
        {"api_key": "CuGEqR171v"}, 
    "results": 
        {"user": 
            {   "first_name": "john", 
                "last_name": "smith", 
                "user_id": 93284093, 
                "user_display_name": "jsmith", 
                "email_addresss": "user@example.com"
            }
        }
}
add_card_set
Example URL: http://api.flashcardexchange.com/v1/add_card_set?title=apiTest&tags=one two&description=testing the api&private=true&intent=4
This method is for creating a new card set. The data returned is similar to a card set object returned from get_tag or get_user.

Input Parameters

Parameter Required Description
oauth credentials yes oauth credentials are required for this method.
title yes The title of the card set. This is the main visible identifier of a card set.
description yes The card set description. A longer explanation that augments the title.
tags yes A space separated list of tags, aka keywords, for this flashcard set. Tags are used for searching, in get_tag and for personal organization.
private no A string representation of a boolean value: "true" or "false". The default value is "false".
indent no An option parameter specifing the number of spaces to use for indenting and returning formatted JSON data. This parameter should be ommitted in production environments.

add_card_set Output Example

{
    "response_type": "ok", 
    "parameters": {
        "indent": "4", 
        "description": "testing the api", 
        "tags": "one two", 
        "title": "apiTest", 
        "private": "true", 
        "api_key": "CuGEqR171v"
    }, 
    "results": {
        "description": "testing the api", 
        "card_set_id": 1676608, 
        "title": "apiTest", 
        "flashcards": [], 
        "tags": "one two", 
        "save_count": 0, 
        "creation_date": "2011-02-25", 
        "author": "jch", 
        "author_id": 18732, 
        "flashcard_count": null
    }
}
add_card
Example URL: http://api.flashcardexchange.com/v1/add_card?card_set_id=248187&question=test&answer=test&indent=4
This method is for creating a flashcard. Currently only textual data uploads is available. We will be adding image and audio functionality soon.

Input Parameters

Parameter Required Description
oauth credentials yes oauth credentials are required for this method.
card_set_id yes The id of the card set the flashcard belongs to.
question yes textual data for the question side of the flashcard.
answer yes textual data for the answer side of the flashcard.
side3 no textual data for side 3 of the flashcard.
indent no An option parameter specifing the number of spaces to use for indenting and returning formatted JSON data. This parameter should be ommitted in production environments.

add_card Output Example

{
    "response_type": "ok", 
    "parameters": {
        "answer": "test", 
        "indent": "4", 
        "api_key": "CuGEqR171v", 
        "question": "test", 
        "card_set_id": "993985899999999"
    }, 
    "results": {
        "modified": "None", 
        "question_image_thumbnail_url": "http://www.flashcardexchange.com/cardimages/questions/thumbnails/4/2/43124412.jpg", 
        "side_three": "", 
        "question": "test", 
        "card_id": 43124412, 
        "question_image_url": "http://www.flashcardexchange.com/cardimages/questions/4/2/43124412.jpg", 
        "answer_media_type": 1, 
        "question_media_type": 1, 
        "answer_image_thumbnail_url": "http://www.flashcardexchange.com/cardimages/answers/thumbnails/4/2/43124412.jpg", 
        "answer_image_url": "http://www.flashcardexchange.com/cardimages/answers/4/2/43124412.jpg", 
        "answer_audio_url": "http://www.flashcardexchange.com/audio/answers/43124412.mp3", 
        "answer": "test", 
        "display_order": 25.0, 
        "question_audio_url": "http://www.flashcardexchange.com/audio/questions/43124412.mp3"
    }
}
edit_card
Example URL: http://api.flashcardexchange.com/v1/edit_card?card_id=9381879387&question=test&answer=test&indent=4
This method is for editing a flashcard. Currently only textual data can be edited. We will be adding image and audio functionality soon.

Input Parameters

Parameter Required Description
oauth credentials yes oauth credentials are required for this method.
card_id yes The id of the flashcard being edited. The authenticated user must be the owner of the card set the flashcard belongs to.
question yes textual data for the question side of the flashcard.
answer yes textual data for the answer side of the flashcard.
side3 no textual data for side 3 of the flashcard.
indent no An option parameter specifing the number of spaces to use for indenting and returning formatted JSON data. This parameter should be ommitted in production environments.

edit_card Output Example


{
    "response_type": "ok", 
    "parameters": {
        "answer": "test3", 
        "indent": "4", 
        "api_key": "CuGEqR171v", 
        "question": "fromtheapi3", 
        "card_id": "21816825"
    }, 
    "results": {
        "modified": "2009-04-28 14:45:39.421313-07:00", 
        "question_image_thumbnail_url": "http://www.flashcardexchange.com/cardimages/questions/thumbnails/6/1/21816825.jpg", 
        "side_three": "", 
        "question": "fromtheapi3", 
        "card_id": 21816825, 
        "question_image_url": "http://www.flashcardexchange.com/cardimages/questions/6/1/21816825.jpg", 
        "answer_media_type": 1, 
        "question_media_type": 1, 
        "answer_image_thumbnail_url": "http://www.flashcardexchange.com/cardimages/answers/thumbnails/6/1/21816825.jpg", 
        "answer_image_url": "http://www.flashcardexchange.com/cardimages/answers/6/1/21816825.jpg", 
        "answer_audio_url": "http://www.flashcardexchange.com/audio/answers/21816825.mp3", 
        "answer": "test3", 
        "display_order": 23.0, 
        "question_audio_url": "http://www.flashcardexchange.com/audio/questions/21816825.mp3"
    }
}
delete_card
Example URL: http://api.flashcardexchange.com/v1/delete_card?card_id=9381879387&indent=4
This method is for deleting a flashcard.

Input Parameters

Parameter Required Description
oauth credentials yes oauth credentials are required for this method.
card_id yes The id of the flashcard being deleted. The authenticated user must be the owner of the card set the flashcard belongs to.
indent no An option parameter specifing the number of spaces to use for indenting and returning formatted JSON data. This parameter should be ommitted in production environments.

delete_card Output Example

{
"response_type": "ok", 
    "parameters": {
        "api_key": "CuGEqR171v", 
        "indent": "4", 
        "card_id": "21816825"
    }, 
"results": "deleted"
}
delete_card_set
Example URL: http://api.flashcardexchange.com/v1/delete_card_set?card_id=9381879387&indent=4
This method is for deleting a flashcard.

Input Parameters

Parameter Required Description
oauth credentials yes oauth credentials are required for this method.
card_set_id yes The id of the card set being deleted. The authenticated user must be the owner of the card set.
indent no An option parameter specifing the number of spaces to use for indenting and returning formatted JSON data. This parameter should be ommitted in production environments.

delete_card_set Output Example

{
"response_type": "ok", 
"parameters": {
    "api_key": "CuGEqR171v", 
    "indent": "4", 
    "card_set_id": "1680422"
}, 
"results": "deleted"
}
get_directory
Example URL: http://api.flashcardexchange.com/v1/get_directory?api_key=CuGEqR171v
This method will return an organized list of tags for browsing.

Input Parameters

Parameter Required Description
api_key yes Your application key.
indent no An option parameter specifing the number of spaces to use for indenting and returning formatted JSON data. This parameter should be ommitted in production environments.

get_directory Output Example

{
    "response_type": "ok", 
    "parameters": {
        "api_key": "CuGEqR171v", 
        "indent": "4"
    }, 
    "results": [
        {
            "tags": [
                {
                    "tag": "Soccer", 
                    "title": ""
                }, 
                {
                    "tag": "Football", 
                    "title": ""
                }, 
                {
                    "tag": "Basketball", 
                    "title": ""
                }, 
                {
                    "tag": "Baseball", 
                    "title": ""
                }
            ], 
            "title": "Sports"
        } 
    ]
}
Copyright © 2001-2012 Collective Research
API | News | About | Help | Terms of Service | Privacy Policy