Yelp search API


Yelp, my favorite local review site, launched a data API today.

I was half hoping that it would use the draft OpenSearch Geo extensions that Andrew has been working on, but after taking a look, the API is richer in scope than what the geo extension is designed for. Though as you can see below, the geo extensions could still offer a complement to the Yelp API.

Moreover, Yelp made the perfectly reasonable choice to syndicate their search results in a JSON format (example), rather than with a more bulky XML document.

Which gets me again thinking about documenting a JSON-based output format for OpenSearch results. Given OpenSearch's agnostic relationship with syndication formats, and my own long-standing assertion that XML is merely one serialization possibility for Atom, there is nothing really stopping us from adopting JSON+OpenSearch.

In fact, here's what an OpenSearch description document might look like for a simple (i.e., not comprehensive) Yelp search request:

<?xml version="1.0" encoding="UTF-8"?>                                                                                                                                                                                      
<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/"
                       xmlns:yelp="http://www.yelp.com/developers/documentation/search_api">                                                                                                                                                        
  <ShortName>Yelp Search</ShortName>                                                                                                                                                                                   
  <Description>Use Yelp.com to search local businesses.</Description>                                                                                                                                                       
  <Tags>yelp</Tags>                                                                                                                                                                                            
  <Contact>admin@example.com</Contact>                                                                                                                                                                                
  <Url type="application/json"                                                                                                                                                                                              
       template="http://api.yelp.com/business_review_search?term={searchTerms}&amp;tl_lat={yelp:tllat}&amp;tl_long={yelp:tllong}&amp;br_lat={yelp:brlat}&amp;br_long={yelp:brlong}&amp;num_biz_requested={count}&amp;ywsid={yelp:ywsid}"/>                                                                                                                                     
</OpenSearchDescription>


Or even more fun, one that tweaks the Yelp API a bit to support the OpenSearch Geo notion of bounding boxes instead of explicit corners:

<?xml version="1.0" encoding="UTF-8"?>                                                                                                                                                                                      
<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/"
                       xmlns:geo="http://a9.com/-/opensearch/extensions/geo/1.0/"
                       xmlns:yelp="http://www.yelp.com/developers/documentation/search_api">                                                                                                                                       
  <ShortName>Yelp Search</ShortName>                                                                                                                                                                                   
  <Description>Use Yelp.com to search local businesses.</Description>                                                                                                                                                       
  <Tags>yelp</Tags>                                                                                                                                                                                            
  <Contact>admin@example.com</Contact>                                                                                                                                                                                
  <Url type="application/json"                                                                                                                                                                                              
       template="http://api.yelp.com/business_review_search?term={searchTerms}&amp;box={geo:box}&amp;ywsid={yelp:ywsid}"/>                                                                                                                                     
</OpenSearchDescription>


Nice.

...

Somewhere out there is a complete version of a OpenSearch+Local spec I wrote for the old A9 local search engine... I wonder if anyone still has it; it might be worth digging up. Of course, that version used a payload of XHTML+microformats, which had some neat properties of its own.

In any case, the Yelp API is very cool. I hope to see some amazing apps built around an already fantastic service!

...

Update: Fixed a grammar error.