Upcoming Changes to the Finding API for Affiliates

May 12th, 2011 | eBay Partner Network Team

api1

The eBay API is the most robust tool we offer our publishers today. You can use the API to get real-time information for all eBay listings – with the flexibility to best meet the needs of your application. The Finding API is the most commonly used API for accessing eBay search results, with a wide selection of filters and other search criteria. The Finding API represents the latest in eBay search technology with improved performance and scalability over the former search API’s.

The week of May 23rd we will be launching some changes to the click URL’s that are provided in eBay’s Finding API calls. As you probably know, many eBay API calls will return properly formatted ePN links in the response if you provide your tracking information in the API call.

Here’s a sample Finding API call with affiliate tracking:

http://svcs.ebay.com/services/search/FindingService/v1?OPERATION-NAME=findItemsByKeywords&SERVICE-VERSION=1.9.0&SECURITY-APPNAME=Your-App-ID&RESPONSE-DATA-FORMAT=XML&REST-PAYLOAD&affiliate.networkId=9&affiliate.trackingId=1234567890&affiliate.customId=mycustomid&
sortOrder=EndTime&paginationInput.entriesPerPage=2&keywords=elmo

In the response to this call, you currently see click URL’s that look like this:

http://rover.ebay.com/rover/1/711-53200-19255-0/1?campid=1234567890&customid=mycustomid&toolid=0&mpre=http%3A%2F%2Fcgi.ebay.com%2F
Sesame-Street-Fisher-Price-2008-Farmer-Country-Elmo-11-%2F190527439548%3Fpt%3DLH_DefaultDomain_0

We will be updating this link with the correct Tool ID and a simplified Item ID link structure (to replace the Custom URL link structure that is currently in place). Two new parameters will also be added – lgeo and vectorid. These are for internal use and shouldn’t be modified. This is how the link will look after these changes are made:

http://rover.ebay.com/rover/1/711-53200-19255-0/1?ff3=2&toolid=10041&campid=1234567890&customid=mycustomid&lgeo=0&vectorid=229466&item
=190527439548

It’s very important that you adopt these changes in your applications. Providing your tracking information and using the proper Tool ID will ensure that you are getting the correct ePN click URL’s and will automatically populate the correct Tool ID for use in your reports. For more information on how to specify your ePN tracking information, please refer to the Finding API documentation.

You should also take a minute to let us know your eBay Developer Program User ID by logging into to the ePN portal and going to Account > Business Information. By linking your accounts within ePN, we can better serve you if there are ever any issues with the API and reach you directly with any updates on new API capabilities.

Still Using the Shopping and Trading APIs for Search Calls?

The eBay Developer Program has posted more information on their blog regarding the deprecation of the following API calls that are popular among affiliates:

• Shopping APIs: FindItemsAdvanced and FindItems
• Trading APIs: GetSearchResults and GetCategoryListings

These API calls will not be available after October 2011 and you may start to receive warning messages in early June if you are still using these calls. Please be aware that your applications may be disrupted if you are not properly handling error messages that are returned from the API.

Here are some highlights from the Developer Program blog post that we hope you find useful in planning your migration from the Shopping/Trading API calls to the Finding API.

Features Only Available in Finding API:

1. Retrieve aspect histograms and filter by aspects and/or domains

2. Support new search capabilities:

  • Item Condition histogram and filters
  • Restrict searches to as many as 3 categories at a time
  • Expedited Shipping filters
  • Top-Rated Sellers Only filter
  • Returns Accepted Only filter

3. Image Search API (findItemsByImage): expand eBay’s capabilities in Fashion to developers for the “More Like This” functionality.

4. Three sizes of gallery image: 140×140, 96×96, 80×80 that users can choose to use based on their application’s needs.

5. Future enhancements to picture URL, Multi-variations, LocatedIn etc. filters and more will be released in May.

How Can I Learn More About Migrating to the Finding API?

The following migration guides map input and output fields for GetSearchResults in the Trading API and FindItemsAdvanced in the Shopping API to the corresponding input and output fields in findItemsAdvanced in the Finding API:

Please feel free to contact the eBay Developer Program for questions or more information on Finding API or migration.

-The eBay Partner Network Team

  • http://www.helios825.org/ helios825

    Thanks very much for posting this — I always love it when ePN posts detailed tech updates like this, as it’s helpful for we API developers. Coolness.

    I’m wondering… Will these changes happen to also effect what the rover servers (not the API servers) actually *expect* in link syntax upon a user click? Some of us affiliates don’t actually use the ePN-formatted rover links that are returned from the API — instead we build our own ePN affiliate links dynamically, in tandem with custom promotional content and often as a result of multiple API calls. In my case, when building such links, I follow a similar format to what the API has been using for many years, bereft of these new parameters like “vectorid”, etc.

    For folks in this camp (those of us who “roll our own”), after we insert the proper ToolID (I like using 10034 to represent homebrewed affiliate links)…

    1) Can we continue to use the CustomURL format for specific items, instead of the ItemID format? (I’m guessing so.)

    2) Do we need to add in new parameters like “igeo” and “vectorid” and “ff3″ to be compliant? If so, please give us guidance on required vs. optional params, acceptable parameter values, etc. Thanks.

    I know there are other affiliates like me who also use this level of automation in their businesses and would really appreciate being made aware of any changes along the continuum of how ePN affiliate link syntax is interpreted and credited to our accounts.

    Thanks!

    -helios825

  • Scott

    Helios825,

    Thanks for posting your comment. I’m going to try and get the answers to your questions, but keep in mind I won’t be able to post them here until next week until after the “freeze” on the blog is lifted. See here:

    http://www.ebaypartnernetworkblog.com/en/2011/05/pardon-the-mess-while-we-upgrade-the-blog/

    Just wanted you to know that I’m on it.

    -Scott

  • al

    findItemsByImage ?
    must have missed a memo on that one.

    Vectorid and ff3 have been mentioned, but not explained in the blog with slightly different names: http://www.ebaypartnernetworkblog.com/en/2009/05/new-link-generator-tool-additional-information/
    ff3 looks to be the same function as type= and vectorid looks the same as the placement/routing code.
    I assume lgeo is a boolean for geotargeting.

    I’ve been using older LinkGen type 4 (customURL) links to target search and single items.
    I too use toolid 10034 as requested by EPN before. (mixed API calls)
    What is 10041 intended for?
    An update to this would be useful:
    http://www.ebaypartnernetworkblog.com/en/2009/11/the-importance-of-using-the-correct-tool-id/

    I think most of us that use the API in this way opt for the simplest format we can get.

    One point that is probably understood, but I think important to make is that caching eBay results short term is important on our end for performance reasons. So any rover code on eBay’s end should not assume that API calls are made on a one to one basis for each page displayed. e.g. I’ve seen APIs from other companies that want the user’s IP address to be included in the API call. Data from one API call may be served to hundreds of users. So it’s somewhat important that we know what the parameters are intended to accomplish so that we correctly implement them.

  • Scott

    Al,
    Yes, “vectorid” and “ff3” are the same parameters as the standard link structure (from Link Generator), without the “icep_” prefix. We are hoping to simplify and shorten the link structure where possible, the API is the first tool to have this enabled. The “lgeo” parameter will be used in a future geo-targeting feature, and should not be confused with the geo-targeting that is currently offered by Link Generator.
    I would recommend that you adopt the newer link format for your item links, instead of the “older LinkGen type 4” format. For search results, the older format may be the best route for more complex search queries, but item links should be updated to the latest format so you can take advantage of the future optimization features (like enhanced geo-targeting and landing page optimization).
    For the Tool ID’s, you should continue to use the tool ID for multiple API calls. Tool ID 10041 is the new tool ID for the findItemsByKeyword call in the Finding API. Before these changes, the Finding API was not including a valid tool ID in the click URL.
    Lastly, we don’t assume a one-to-one relationship for API calls to pages/links. However, if you do use the API results directly and want to have the latest click URL format, then we offer a proper click URL in the results.
    I’m so glad to see you using these blog posts for reference!
    Thanks,
    Scott

  • Scott

    John – Yes, that is correct.
    -Scott

  • John

    So if we currently provide the Finding API with our tracking id and use the returned links, we should be able to continue using the returned links without any disruption or modification to our applications? (I assume this is correct)

  • Ben Johnson

    Hi Scott,

    I would also really appreciate the answers to the above questions, as at present it’s not really being made clear.

    Can you let us know once you have the answers.

    Thanks
    Ben

  • Ben Johnson

    Hi,

    There doesn’t seem to be any updated documentation on these changes, I’ve got applications with thousands of customers I need to update. Is there going to be an proper documentation showing how to create the new links. Currently a US call returns a URL with cgi.ebay.com in to redirect visitors to the US site and the UK call returns cgi.ebay.co.uk in the rover URl to redirect to the .co.uk site. There’s no evidence of this in the new URL structure, how is this meant to be handled?

    Is there going to be a transitional period?

    Thanks

  • TheShamanMarketer

    Thanks for the detailed update that makes it clear for “semi-technical” folks as well…
    Just one question remaining: what about sites that use “old” applications like BANS for the auctions part?

    Is the new format “backward compatible” or will we need to rebuild our sites from scratch (hey, “change” is good, *sigh*)?

    Martin

  • Scott

    Martin,

    The new format is “backward compatible” for people that were using the click URL directly – and not making any modifications. For “old” applications, compatibility would depend on how (and if) they are using the Finding API. If those applications were never using the click URL returned by the Finding API, then they would not be impacted.

    -Scott

  • helios825

    Thanks for looking into that, Scott!

    -helios825

  • Brandi Young

    “4. Three sizes of gallery image: 140×140, 96×96, 80×80 that users can choose to use based on their application’s needs.”

    I only get one gallery image back from a findItemsAdvanced call to the API – the size of which is unstated and not something I can request. Will you please email me about where I may learn how to get a specific size?

    Thanks!

    Brandi

  • Ben

    Just interested if anyone is going to provide answers to any of the questions which have been asked, both by myself and the OP. Or are eBay just intending on rolling out changes affecting multiple APPs and not giving clear documentation on it? The eBay developer forums don’t have any answers, the Finding API docs are the old ones and don’t cover anything as far as I can see to do with the changes.

    Thanks

  • Scott

    Ben,

    We were hoping that this blog post could get you most of the information that you would need to plan for this change. Many people will not need to make any changes on their own applications if they are using the click URL provided by the API exactly as it’s provided, or if they are not using it at all. If you are using the click URL provided by the API and modifying it in any way, then you should read more about the changes detailed in this blog post. Please let us know if you have detailed questions or concerns about the changes. The API documentation should be updated when the changes go live.

    -Scott

  • Jonathan Castro

    I found this post rather confusing. Are you saying that the correct viewItemURL will be returned when making calls as before? I don’t create the URLs myself. Presumably eBay will automatically insert the correct ToolID, etc, in the returned URL.

  • Scott

    Jonathan,

    Yes, the correct value for the will be returned if you are passing in your affiliate tracking details in your API call.

    Thanks,

  • Scott

    Helios825 – This is just a change to how the API returns the rover links, no changes are required to your existing links.

  • http://www.helios825.org/ helios825

    @Scott: Thanks for confirming that! :-)

    @Brandi: Pending a formal answer to your question, I know of a pretty clever (and easy) trick that a number of eBay developers use to retrieve a gallery image in any of those sizes on demand. If you click my name above, then look for my email addy at the bottom of the page, email me, and I can dig up those threads on the eBay Developer forum that explain it all.

    -helios825

  • Scott

    No problem Helios825. Thank you for helping Brandi out.

    -Scott

  • helios825

    @Brandi: I’m not sure if you’re still following this blog post, but I recently came across the formal way to instruct the API to return the additional gallery image sizes. You’ll want to learn about and use, within your API call, the new Output Selector called ‘GalleryInfo’ that will generate more gallery URLs for your use.

Join the eBay Partner Network

Drive traffic to one of our partners and get paid for it.

Join Now!