Talpa Search API Documentation
General Notes
Talpa Search is an innovative way to search for books, available at https://www.talpasearch.com.
Usage Limits
Free usage is provided so developers can get an idea of how the API works. To use the Talpa API at scale, contact talpa@librarything.com.
- Free usage is restricted to 50 queries per day.
- Free usage is restricted to 1 query per second.
Search Books API
Although called "Search Books," this API searches books, music and movies.
Request Format
Examples
These examples work without a developer token, and do not count toward usage restrictions.
- astronaut stranded on mars —
https://www.librarything.com/api/talpa.php?search=astronaut+stranded+on+mars&token=YOUR_TOKEN - 1980s teen movies —
https://www.librarything.com/api/talpa.php?search=1980s%20teen%20movies&token=YOUR_TOKEN
Base URL
The base URL is: https://www.librarything.com/api/talpa.php
Required Parameters
- search — The search query, or
- query_id — The
query_idof a previous query. (Used instead of the search parameter.) - token — Your LibraryThing API token.
Optional Parameters
- page — The page number of the results, counting from 1. By default, the page is 1.
- limit — How many results to return. By default, the limit is 20; maximum 50.
- nocaching — Use
nocaching=1to turn result caching off. By default, caching is on.
Library-Specific Parameters
Libraries using the Talpa Search API can prefer and limit searches to their collections. Contact talpa@librarything.com for more information.
Return Format
The Talpa Search API responds with a request and a response, or with an error.
- request — This object provides information about the search request.
- query — The search query string as submitted.
- page — The page number requested.
- limit — The number of results requested.
- response — The response object. Each object includes:
- query_id — A unique identifier for the query.
- results — The total results available.
- pages — How many result pages are available.
- searchtook — The time taken to process the query, in seconds.
- version — The version of the Talpa engine.
- resultlist — A list of results, if any. (See below.)
- warnings — A list of warnings, if any. (See below.)
Error
The error object occurs when there is a system error.
- code — An error code.
- explanation — What went wrong.
Resultlist
The resultlist is an array of objects, found under the response, representing the works found in the search. Each object includes:
- rank — The ranking of the work in the search results.
- title — The title of the work. This is provided for debugging purposes only. You should use the appropriate bibliographic information in your system.
- work_id — A unique identifier for the work. You can see the work on LibraryThing by going to https://www.librarything.com/work/[work_id]
- isbns — An array of all ISBNs associated with the work. All ISBNs are given in their ISBN13 form.
- upcs — An array of all UPCs associated with the work.
Warnings
The warnings are a occasional array of objects, found under the response. Warnings may be returned instead of or together with results.
- reason — The name of the problem. See below "Warning Reasons" for warnings and their description.
- technical_explanation — A description of the reason, addressed to the developer.
- wording — A short description of the problem, for debugging or display.
- level — The priority of the warning 0-100. A higher priority is more important. We suggest that only one warning be shown—the highest level one.
- stop — Should the warning be just a warning, or a bar to showing any results? Values are true or false.
Miscellaneous API Details
Warning Reasons
Here are the possible warnings (as of Version 1.0), and their technical_explanation.
- default — The default, non-specific warning message (i.e., "Unable to display results").
- offensive — The search was classified offensive, and may bring up offensive results. Offensive searches include hate speech, insults and threats.
- subjective — Results drawn more from "recommendations" than "search."
- selfharm — Search suggested an intent to suicide or self harm.
- coversearch — The search mentions the item's cover. You may want to use our Cover Search API instead.
Error Codes
- 2 — Token does not exist or is deleted.
- 101 — You have exceeded your daily API quota.
- 102 — You have exceeded your rate-limit.
- 201 — There was a problem with the API: returning events.
- 999 — Talpa Search is currently experiencing high demand.
Version Changes
Version 1.0 (August 26, 2024)
- Before API version 1.0, token was called key, which continues to work for backward compatibility
- The format is now always JSON, with no option to specify XML or Array.
Example Query and Response
Request
https://www.librarything.com/api/talpa.php?token=YOUR_TOKEN&search=1980s%20teen%20movies
Response
{
"request": {
"query": "1980s teen movies",
"page": 1,
"limit": 20,
"token": "YOUR_TOKEN",
"developer": {
"dailyquota": "YOUR_QUOTA",
"remaining": "YOUR_REMAINING"
}
},
"response": {
"query_id": "0f3e-cf94-3f7d-4de7",
"searchtook": 1.38,
"results": 197,
"pages": 10,
"version": "1.0",
"resultlist": [
{
"rank": 1,
"title": "Sixteen Candles [1984 film]",
"work_id": 2725072,
"score": 171922.32,
"isbns": [
"9786305078067",
"9781558809857",
"9780783252117",
"9786312163664",
"9786316544087"
],
"upcs": [
"025192114021",
"760137358084",
"025192365140",
"096898007634",
"025192139949",
"025192195051",
"025195018678",
"014381427028"
]
},
{
"rank": 2,
"title": "The Breakfast Club [1985 film]",
"work_id": 2208622,
"score": 162074.66,
"isbns": [
"9780783226873",
"9780783283852",
"9786315855399",
"9781681433844",
"9781681433837"
],
"upcs": [
"715515207010",
"044004440639",
"025192130847",
"025192274534",
"025192274541",
"096898016735",
"025192021022",
"025192315626",
"715515207119",
"025195018647"
]
},
{
"rank": 3,
"title": "Ferris Bueller's Day Off [1986 film]",
"work_id": 940051,
"score": 73731.24,
"isbns": [
"9780792158844",
"9780792100225",
"9781415715338",
"9780792156345",
"9781415748756"
],
"upcs": [
"097361429243",
"883929301829",
"883929304424",
"097360189049",
"097361379548",
"097360313369",
"097360189070",
"097360313345",
"097360189025",
"032429109552",
"973601890496",
"031504018901",
"032429256782",
"689721384301",
"883929306190",
"097360313321",
"097360189032"
]
},
{
"rank": 4,
"title": "Pretty in Pink [1986 film]",
"work_id": 1160021,
"score": 36043.33,
"isbns": [
"9780792181750",
"9781415718438",
"9781415742822",
"9786316726162",
"9786318754125"
],
"upcs": [
"883929303366",
"097360421644",
"097360185843",
"097360185829",
"097360185881",
"097364216444",
"097360421668",
"032429257758",
"097361380544",
"689721950742"
]
},
{
"rank": 5,
"title": "Fast Times at Ridgemont High [1982 film]",
"work_id": 682533,
"score": 23073.05,
"isbns": [
"9780783239934",
"9781417011001",
"9781417011018",
"9781681438252",
"9781681438245"
],
"upcs": [
"047897701535",
"025192130809",
"025193128829",
"096894182762",
"025192544620",
"025192544521",
"025192053023",
"025192351853",
"715515257916",
"715515258012",
"096898399333"
]
},
{
"rank": 6,
"title": "'80s Comedies Spotlight Collection: The Breakfast Club \/ Sixteen Candles \/ Fast Times at Ridgemont High",
"work_id": 16813713,
"score": 20999.99,
"upcs": [
"025192117442"
]
},
{
"rank": 7,
"title": "Heathers [1988 film]",
"work_id": 317937,
"score": 17465.1,
"isbns": [
"9780764002380",
"9781560687214",
"9780764000454",
"9786303265759",
"9786314377717"
],
"upcs": [
"013131067293",
"014381732252",
"014381729221",
"092091910139",
"013131598995",
"013131140590",
"807297063790"
]
},
{
"rank": 8,
"title": "The Lost Boys [1987 film]",
"work_id": 701680,
"score": 15108.83,
"isbns": [
"9780790792200",
"9780790733517",
"9781419862014",
"9781419869488",
"9780780669017"
],
"upcs": [
"883929453047",
"085391184928",
"883929024315",
"883929273171",
"085391174820",
"883929165162",
"085393353025",
"883929251711"
]
},
{
"rank": 9,
"title": "Bill & Ted's Excellent Adventure [1989 film]",
"work_id": 1745896,
"score": 13130.67,
"isbns": [
"9780792851523",
"9780792867463",
"9781558474031",
"9786314853303",
"9786315483257"
],
"upcs": [
"097428010612",
"023568087412",
"027616869265",
"883904284925",
"027616121301",
"027616925602"
]
},
{
"rank": 10,
"title": "The Outsiders [1983 film]",
"work_id": 7747039,
"score": 12276.17,
"isbns": [
"9780790703220",
"9780790740843",
"9780790768397",
"9781419810800",
"9781419873379"
],
"upcs": [
"085391131038",
"883929272495",
"883929320387",
"883929035427",
"085392255429",
"085391131021",
"012569705968",
"883929783656"
]
},
{
"rank": 11,
"title": "Footloose [1984 film]",
"work_id": 107589,
"score": 11625.7,
"isbns": [
"9780792181132",
"9781415702901",
"9781415760963",
"9781415760970",
"9786314959845"
],
"upcs": [
"097361456645",
"097360158939",
"097360534146",
"097360158946",
"097361456546",
"883929304363",
"097361456669",
"032429259196",
"032429256874",
"097361379647",
"097360534160",
"097360158922",
"883929306176",
"883929319176"
]
},
{
"rank": 12,
"title": "Some Kind of Wonderful [1987 film]",
"work_id": 5300559,
"score": 7641.84,
"isbns": [
"9780792181774",
"9781415718551",
"9780792100287",
"9781415742877",
"9786318754156"
],
"upcs": [
"032429264190",
"097361381046",
"097360422061",
"883929304486",
"097363197942",
"097360422047"
]
},
{
"rank": 13,
"title": "Say Anything [1989 film]",
"work_id": 645389,
"score": 7254.18,
"isbns": [
"9786306842780",
"9780793917013",
"9786301412766",
"9786313160310",
"9786313160327"
],
"upcs": [
"689721606489",
"780177659767",
"024543017646",
"024543617266",
"024543024545",
"024543016151",
"024543563631",
"086162170133",
"024543024521",
"024543024538"
]
},
{
"rank": 14,
"title": "Dirty Dancing [1987 film]",
"work_id": 509948,
"score": 6047.36,
"isbns": [
"9780805104820",
"9780784013380",
"9780784010211",
"9786313526390",
"9786316740656"
],
"upcs": [
"028485160132",
"028481601332",
"012236212829",
"012236212775",
"012236146995",
"028485114005",
"012236109464",
"012236108733",
"012236044406",
"031398253754",
"012236052333",
"057373211625",
"012236100027",
"057373174616",
"689721117732",
"065935200734",
"014381517262",
"031398253761",
"012236147022",
"012234950532",
"097428010025"
]
},
{
"rank": 15,
"title": "Dead Poets Society [1989 film]",
"work_id": 112538,
"score": 5656.8,
"isbns": [
"9786301627764",
"9781558908871",
"9780788853647",
"9781558909472",
"9786305144168"
],
"upcs": [
"765362161034",
"786936761481",
"012257947038",
"717951000682",
"786936239911"
]
},
{
"rank": 16,
"title": "Risky Business [1983 film]",
"work_id": 10547636,
"score": 5555.77,
"isbns": [
"9780790732206",
"9780790740652",
"9786312281207",
"9781419873928",
"9781419873935"
],
"upcs": [
"853911323252",
"085391132332",
"883929014897",
"883929272969",
"883929269877",
"085391715733",
"883929002931",
"085391132325"
]
},
{
"rank": 17,
"title": "Better Off Dead [1985 film]",
"work_id": 107491,
"score": 5333.28,
"isbns": [
"9780792178965",
"9780793970834",
"9781415742600",
"9781415759042",
"9781787633735"
],
"upcs": [
"689721084843",
"097361378343",
"097361452241",
"086162708336",
"097368719149"
]
},
{
"rank": 18,
"title": "Real Genius [1985 film]",
"work_id": 318075,
"score": 4618.88,
"isbns": [
"9780767881203",
"9780800186449",
"9780800106812",
"9786302824551",
"9786317253285"
],
"upcs": [
"043396077348",
"043396605688"
]
},
{
"rank": 19,
"title": "The Last Starfighter [1984 film]",
"work_id": 1000574,
"score": 4437.6,
"isbns": [
"9780783230566",
"9780783217031",
"9786300183483",
"9786312938231",
"9786316639684"
],
"upcs": [
"025192183713",
"025192380754",
"047897800788",
"025192352430",
"025192108082",
"096898007832",
"025195053587",
"025192019975",
"025192051920"
]
},
{
"rank": 20,
"title": "Adventures in Babysitting [1987 film]",
"work_id": 733314,
"score": 4276.16,
"isbns": [
"9780788816888",
"9786305428053",
"9781558905955",
"9786301008945"
],
"upcs": [
"717951003300",
"012257595031"
]
}
]
}
}