Parameters
Book Search Criteria
Note on URL Encoding
All URL parameters must be encoded with ISO-8859-1 (Latin-1), not UTF-8. For example, the author name "Hölderlin" must be encoded as "H%F6lderlin". Spaces and other special characters must also be URL encoded. Many URL-encoding utilities default to UTF-8, which would encode "ö" as "%C3%B6" rather than the required "%F6"; make sure yours targets the ISO-8859-1 character set.
Primary Search Parameters
There are five primary search parameters, of which at least one must be specified in every search request.
| Parameter | Description | Example Values |
|---|---|---|
| isbn | A 10- or 13-character ISBN value. | 9780708915110, 3799503005 |
| author | The name or names of all authors of a book. | Margaret+Atwood |
| title | The title of a book. | Bluebeard%27s+Egg+and+Other+Stories |
| keyword | This word is searched against all text fields in a book listing, including author, title, publisher, description and the keywords assigned by a seller. Search using this field if you need to scan the entire listing, rather than a specific field. | cooking |
| pubname | Search by publisher name. | Random+house |
Secondary Search Parameters
Secondary search parameters are optional criteria that may be added to any search request to refine a search. Secondary search parameters that are not provided in the search request will be automatically set to the default values, as outlined below (e.g., minprice is assumed to be 0 when the minprice parameter is not provided).
| Parameter | Description | Accepted Values | Default | Notes |
|---|---|---|---|---|
| maxprice | Limits the search to only books below the value specified. | 0 – max integer | No limit, USD | Must be a positive number. Value is in USD only. |
| minprice | Limits the search to only books above the value specified. | 0 – max integer | No minimum (0), USD | Must be a positive number. Value is in USD only. |
| vendorlocation | Limits the search to sellers located in the country specified. | Two or three letter ISO country code | Search all countries. | ISO3 codes are recommended. As of August 1, 2008, we no longer accept the two-letter country code gb. Use uk instead. If this changes in the future, we will maintain compatibility with uk. |
| bookcondition | Filters results by book condition. | new, used, asnew, fine, nearfine, verygood, good, fair, poor, asdescribed | Search all book conditions. | We recommend using standard condition terms for more precise filtering. Note: legacy terms newonly and usedonly are still supported if used. |
| minsellerrating | Filters results by seller rating. | 1, 2, 3, 4, 5 | Search all ratings. | AbeBooks' seller ratings are based on a seller's completion rate. |
| binding | Filters results by cover type. | softcover, hardcover | Search all bindings. | |
| signed | Limits results to signed books. | yes | Search both signed and unsigned. | |
| freeshipping | Limits results to books that are shipped without cost to the USA. | yes | Search all shipping rates. | Only applies to the USA. Free shipping prices may not be cheaper than prices including the shipping cost. Use total price plus relevant shipping destination to identify the best price. |
| groupcode | Limits results to books from sellers in a particular group. | FREESHIP (free shipping to the USA), FREESHIPFR (France), FREESHIPDE (Germany), FSIRL (Ireland), FREESHIPIT (Italy), FREESHIPNZ (New Zealand), FREESHIPES (Spain), FREESHIPUK (UK), FREESHIPAU (Australia), FREESHIPCA (Canada), FREESHIPWW (worldwide) | Search all sellers. | Free shipping prices may not be cheaper than prices including the shipping cost. Use total price plus relevant shipping destination to identify the best price. |
| minpubyear | Filters results by minimum publication year. | 1 - 9999 | Search all publication years. | |
| maxpubyear | Filters results by maximum publication year. | 1 - 9999 | Search all publication years. | |
| firstedition | Limits results to first edition books. | yes | Search all editions. | |
| dustjacket | Limits results to books with a dust jacket. | yes | Search books both with and without dust jackets. | |
| vendorid | Searches for books from a particular seller by their AbeBooks seller ID number. | Any AbeBooks seller ID number (integers only). | Search all AbeBooks sellers. | Look up a seller's ID number in the URL of the seller's storefront on the AbeBooks website. |
| pt | Filters results by Product Type. | book (Books and untagged items), mag (Magazines and Periodicals), comic (Comics), music (Sheet Music), art (Art, Prints and Posters), photo (Photographs), map (Maps), ms (Manuscripts and Paper Collectibles). Values can be combined, e.g., pt=art,photo (comma URL encoded as %2C). | Search all Product Types. | Product Type refers only to items that are explicitly tagged by AbeBooks sellers. These items represent a subset of AbeBooks' inventory. Product Type 'Book' refers both to items tagged as books and to all untagged items within AbeBooks' inventory. |
| language | Filters results by listing content language. | Comma separated list of capital letter ISO 639-2 codes, or "N" for unspecified language, e.g., language=DEU,SPA,N | Search all languages. | A maximum of 5 languages (including "N") can be specified in a single query. |
Output Value Parameters
Output value parameters are optional parameters that determine how certain output values, such as shipping price, are calculated.
| Parameter | Description | Accepted Values | Default | Notes |
|---|---|---|---|---|
| allvendorimageurls | Includes all available vendor images. | yes | On output sizes of short and larger, only the best vendor image will be returned. | By default, short and larger output formats provide the best vendor image as a URL. If this parameter is provided, all available image URLs are included in two new outputs, Vendor Image Urls Large and Vendor Image Urls Small. The output format does not determine this result. |
| currency | Item price and shipping cost(s) will be returned in the currency specified. | Three letter ISO currency code | See the Specifying Domains section under Additional Features for details. | To see a current list of supported payment currencies, go to any of our domains. You can set your parameter value to any of the accepted values. If you use an accepted value that is not a supported payment currency, the price returned is a reference only. If you do not set a parameter value, the default is used. |
| destinationcountry | All shipping prices will be calculated with the destination country set to the country specified. | Two or three letter ISO country code | USA | Only the following countries are available: Australia, Belgium, Canada, France, Germany, Italy, Japan, Spain, Switzerland, USA and UK. All other countries will use the "International" shipping price, as specified by the seller. |
| shippingdetails | Includes second book ship cost, min/max ship days and standard/priority shipping rates. | yes | Search all shipping rates. | If this parameter is not set, second book ship cost and min/max ship days will all = 0, and the shiprate parameter will be ignored. |
| shiprate | Either S or P. All shipping rates will be calculated as either S (standard) or P (priority) rates. | S, P | S | To use this parameter, shippingdetails=yes must also be included in the search request. |
| targetsite | Sets the listing URL to the requested AbeBooks domain as well as the corresponding country and currency. Excludes certain books where advertising is prohibited in the corresponding country. | abebooks.com, abebooks.co.uk, abebooks.fr, abebooks.de, abebooks.it, iberlibro.com, zvab.com | abebooks.com | To change the country, set destinationcountry. To change the currency, set the currency parameter. |
Book Record Format
The outputsize parameter determines how much detail is included in each search result. The less data requested, the faster the results will be returned.
Values: outputsize=micro, outputsize=short, outputsize=medium (default), outputsize=long
Note: If a particular field is not populated for a listing, that field will be omitted from the record.
| Output Name | Micro | Short | Medium | Long | Notes |
|---|---|---|---|---|---|
| Result count | Y | Y | Y | Y | How many books are returned given specific criteria. |
| Book ID | Y | Y | Y | Y | An AbeBooks internal listing ID. This number is also in the Listing URL below. |
| ISBN 10 and 13 | Y | Y | Y | Y | International Standard Book Number assigned by the book's publisher. |
| Listing condition | Y | Y | Y | Y | Returns value NEW BOOK or NOT NEW BOOK. |
| Item condition | Y | Y | Y | Y | Returns values new, as new, fine, very good, good, near fine, fair or poor. This is a more granular version of the Listing condition. |
| Quantity | Y | Y | Y | Y | Indicates if a seller offers multiple copies of the same book ID. |
| Vendor currency | Y | Y | Y | Y | The currency in which the seller uploaded their inventory. |
| Listing price | Y | Y | Y | Y | Default listing price as seen on AbeBooks.com. If currency parameter is set, price is in that currency. |
| Total book price | Y | Y | Y | Y | Total book price plus shipping. |
| First book shipping cost | Y | Y | Y | Y | |
| Extra book shipping cost | Y | Y | Y | Y | shippingdetails=yes must be included. The July 2023 shipping update supports more complex shipping rules, so this field may no longer display meaningful values. It is not deprecated; instead the field will return 0.0. |
| Min and max shipping days | Y | Y | Y | Y | shippingdetails=yes must be included. |
| Listing URL | Y | Y | Y | Y | Link to the AbeBooks listing detail page on the AbeBooks.com domain. You can display the listing on any other AbeBooks site by switching the domain accordingly. |
| Author | N | Y | Y | Y | |
| Title | N | Y | Y | Y | |
| Publisher name | N | Y | Y | Y | |
| Catalogue image | N | Y | Y | Y | URL for publisher provided image of book cover. |
| Vendor name | N | N | Y | Y | |
| Vendor location | N | N | Y | Y | City and country. |
| Vendor ID | N | N | Y | Y | A unique ID that identifies a seller on AbeBooks. |
| Seller rating | N | N | Y | Y | A number between 1 and 5, indicating a seller's completion rate. |
| Keywords | N | N | Y | Y | Additional searchable keywords provided by a seller. |
| Subjects | N | N | N | N | Retired June 2024. Field omitted from record. |
| Binding type | N | N | Y | Y | S indicates softcover binding. H indicates hardcover binding. |
| Edition type | N | N | Y | Y | F indicates the seller has listed the book as a first edition. |
| Book jacket | N | N | N | Y | J indicates the seller has listed the book as having a dust jacket. |
| Publication year | N | N | N | Y | |
| Vendor price | N | N | N | Y | The price as originally specified by the seller, in the original currency. |
| Vendor description | N | N | N | Y | Listing description as provided by the seller. |
| Vendor image | N | Y | Y | Y | URL for seller provided image of book cover. |
| Product Type | N | N | N | Y | Product Type refers to items that are explicitly tagged by AbeBooks sellers as Books, Magazines and Periodicals, Comics, Sheet Music, Art, Prints and Posters, Photographs, Maps or Manuscripts and Paper Collectibles. |
| Vendor Image Urls Large | Y | Y | Y | Y | allvendorimageurls=yes must be included. A list of URLs to large vendor images. |
| Vendor Image Urls Small | Y | Y | Y | Y | allvendorimageurls=yes must be included. A list of URLs to small vendor images. |
| Language | N | Y | Y | Y | The ISO 639-2 code representing the listing's content language, or "N" if language is unspecified. |
Sort Order
The sortorder parameter indicates how results should be sorted. Default is 2 (price ascending).
| Sort Order Integer | Description |
|---|---|
| 0 | Newly listed books first. |
| 1 | Price, descending. |
| 2 | Price, ascending (default). |
| 3 | Sellers in the United Kingdom are displayed first. |
| 4 | Author names, descending. |
| 5 | Author names, ascending. |
| 6 | Book title, descending. |
| 7 | Book title, ascending. |
| 8 | Sellers in Germany are displayed first. |
| 9 | Sellers in France are displayed first. |
| 10 | Sellers in Spain are displayed first. |
| 11 | Sellers in Italy are displayed first. |
| 15 | Seller rating, descending. |
| 17 | Total price, ascending (book price plus shipping). Include the destinationcountry parameter to get shipping costs for the following countries: Australia, Belgium, Canada, France, Germany, Italy, Japan, Spain, Switzerland, USA and UK. All other countries will use the "International" shipping price, as specified by the seller. |
| 20 | Relevance (Beta) |
Limiting Search Results
The number of matching search results returned for each request can be controlled by the maxresults parameter. The fewer results requested, the faster the results will be returned. Default is 20. Maximum is 200.
Additional Features
Specifying Domains
AbeBooks has a number of different domains, each with their own default country and currency:
| Domain | Default Country | Default Currency |
|---|---|---|
| AbeBooks.com | USA | USD |
| AbeBooks.co.uk | GBR | GBP |
| AbeBooks.fr | FRA | EUR |
| AbeBooks.de | DEU | EUR |
| ZVAB.com | DEU | EUR |
| AbeBooks.it | ITA | EUR |
| IberLibro.com | ESP | EUR |
Search Web Services searches AbeBooks.com in USD by default. To search a different domain:
- Use the
targetsiteparameter. - The item price and shipping cost(s) will be returned in the default currency for the chosen domain. To choose a different currency, include the
currencyparameter. - The shipping cost(s) value will be calculated for the default country for the chosen domain. To choose a different country, include the
destinationcountryparameter.
Adding Affiliate Tracking Code
To track Search Web Services links to your affiliate ID, encode the redirect URL returned under listingURL.
Impact Radius:
- Use the following link as a template:
https://affiliates.abebooks.com/c/[Impact_Radius_ID]/77798/2029?u=[ENCODED_REDIRECT_LINK] - Replace
[ENCODED_REDIRECT_LINK]with the encoded redirect link. - Replace
[Impact_Radius_ID]with your Impact Radius ID number, e.g., 12345.
Adding Books to Basket
To send a user directly to the shopping basket, use the following URL structure:
https://www.abebooks.com/servlet/ShopBasketPL?ac=a&ik=14083099173
Where the ik= parameter specifies the Book ID for the book to be added.
To add more than one copy, repeat the same ik= parameter:
https://www.abebooks.com/servlet/ShopBasketPL?ac=a&ik=14083099173&ik=14083099173&ik=14083099173
To add multiple copies of more than one item:
https://www.abebooks.com/servlet/ShopBasketPL?ac=a&ik=10023099123&ik=10023099123&ik=14083099173&ik=14083099173&ik=14083099173
Note: The maximum number of copies that can be added directly to the basket is fifty. If the quantity requested for a given Book ID exceeds availability, the maximum quantity available will be added.
Compressed Search Results
Search Web Services outputs in XML and in faster compressed format (GZIP). To get results in compressed format, include a header indicating that you accept compressed output. Set the Accept-Encoding HTTP Request header to gzip, deflate. When compression is properly enabled, the response header will contain Content-Encoding: gzip.
Appendix: Sample Search Requests
Primary Search Parameters
- Search for ISBN '9780140707052':
https://search2.abebooks.com/search?isbn=9780140707052&clientkey=<your client key here> - Search for author 'William Shakespeare':
https://search2.abebooks.com/search?author=william+shakespeare&clientkey=<your client key here> - Search for title 'Macbeth':
https://search2.abebooks.com/search?title=macbeth&clientkey=<your client key here> - Search for author 'William Shakespeare' and title 'Macbeth':
https://search2.abebooks.com/search?author=william+shakespeare&title=macbeth&clientkey=<your client key here> - Search for keyword 'tragedy':
https://search2.abebooks.com/search?keyword=tragedy&clientkey=<your client key here>
Secondary Search Parameters
- Copies of Macbeth listed for US$ 10.00 or more:
https://search2.abebooks.com/search?title=macbeth&minprice=10&clientkey=<your client key here> - Copies of Macbeth listed for US$ 10.00 or less:
https://search2.abebooks.com/search?title=macbeth&maxprice=10&clientkey=<your client key here> - Copies of Macbeth between US$ 1.00 and US$ 10.00:
https://search2.abebooks.com/search?title=macbeth&minprice=1&maxprice=10&clientkey=<your client key here> - New copies of Macbeth:
https://search2.abebooks.com/search?title=macbeth&bookcondition=new&clientkey=<your client key here> - Copies from sellers with minimum rating of 4:
https://search2.abebooks.com/search?title=macbeth&minsellerrating=4&clientkey=<your client key here> - Hard cover copies of Macbeth:
https://search2.abebooks.com/search?title=macbeth&binding=hardcover&clientkey=<your client key here> - Only signed copies of 1984:
https://search2.abebooks.com/search?title=1984&signed=yes&clientkey=<your client key here> - Copies of Macbeth with free shipping to USA:
https://search2.abebooks.com/search?title=macbeth&freeshipping=yes&clientkey=<your client key here> - Copies of Macbeth published between 1990 and 1995:
https://search2.abebooks.com/search?title=macbeth&minpubyear=1990&maxpubyear=1995&clientkey=<your client key here> - First editions of 1984:
https://search2.abebooks.com/search?title=1984&firstedition=yes&clientkey=<your client key here> - Signed first editions of 1984:
https://search2.abebooks.com/search?title=1984&signed=yes&firstedition=yes&clientkey=<your client key here> - Copies of Macbeth from a specific publisher:
https://search2.abebooks.com/search?title=macbeth&pubname=penguin&clientkey=<your client key here> - Copies of Macbeth with a dust jacket:
https://search2.abebooks.com/search?title=macbeth&dustjacket=yes&clientkey=<your client key here> - Copies of Macbeth from a specific seller:
https://search2.abebooks.com/search?title=macbeth&vendorid=6846184&clientkey=<your client key here> - Maps of Paris:
https://search2.abebooks.com/search?keyword=paris&pt=map&clientkey=<your client key here>
Output Value Parameters
- Pricing in Canadian dollars:
https://search2.abebooks.com/search?title=macbeth¤cy=CAD&clientkey=<your client key here> - Shipping destination to Great Britain:
https://search2.abebooks.com/search?title=macbeth&destinationcountry=GBR&clientkey=<your client key here> - Priority shipping:
https://search2.abebooks.com/search?title=macbeth&shippingdetails=yes&shiprate=p&clientkey=<your client key here> - Default domain to abebooks.de:
https://search2.abebooks.com/search?title=macbeth&targetsite=abebooks.de&clientkey=<your client key here> - Include all vendor images:
https://search2.abebooks.com/search?isbn=9780451161352&allvendorimageurls=yes&clientkey=<your client key here>
Sort Order
- Sorted by highest to lowest price:
https://search2.abebooks.com/search?isbn=0451172817&sortorder=1&clientkey=<your client key here> - Sorted by highest to lowest rated sellers:
https://search2.abebooks.com/search?isbn=0451172817&sortorder=15&clientkey=<your client key here>
Max Results
- Limit output to 25 results:
https://search2.abebooks.com/search?isbn=0451172817&maxresults=25&clientkey=<your client key here>
Appendix: List of All Parameters
| Parameter Name | Parameter Type | Description |
|---|---|---|
| allvendorimageurls | Output Value | Include all available vendor image urls. |
| author | Primary Search | The name or names of all authors of a book. |
| binding | Secondary Search | Filter by cover type. |
| bookcondition | Secondary Search | Filter by book condition. |
| currency | Output Value | Book price and shipping costs will be returned in the currency specified. |
| destinationcountry | Output Value | All shipping prices will be calculated with the destination country specified. |
| dustjacket | Secondary Search | Limit to books with a dust jacket. |
| firstedition | Secondary Search | Limit to first editions. |
| freeshipping | Secondary Search | Limit to only free shipping to USA. |
| groupcode | Secondary Search | Limit results to books from sellers in a particular group. |
| isbn | Primary Search | A 10- or 13-character ISBN value. |
| keyword | Primary Search | Searched against all text fields in a book listing. |
| language | Secondary Search | Filter results by listing content language. |
| maxprice | Secondary Search | Limits the search to only books below the value specified. |
| maxpubyear | Secondary Search | Maximum publication year. |
| minprice | Secondary Search | Limits the search to only books above the value specified. |
| minpubyear | Secondary Search | Minimum publication year. |
| minsellerrating | Secondary Search | Filter by seller rating. |
| pubname | Primary Search | Search by publisher name. |
| pt | Secondary Search | Filters results by Product Type. |
| shippingdetails | Output Value | Includes second book ship cost, min/max ship days and standard/priority ship rates. |
| shiprate | Output Value | Either S or P. All shipping rates calculated as standard or priority. |
| signed | Secondary Search | Limit to signed books. |
| targetsite | Output Value | Sets the listing URL to the requested AbeBooks domain. |
| title | Primary Search | The title of a book. |
| vendorid | Secondary Search | An AbeBooks seller ID number. |
| vendorlocation | Secondary Search | Limits search to sellers in the country specified. |