Json / xml return

API is RESTfull. You can pass application/json as content header and you will get back json (by default you will get back xml). You can see the calls in curl like this:

curl -i -H "Accept: application/json" http://d.2ya.it/dre/api/rest/search/local?appId={AppID}&query=pizza&lat=37.3323&lng=-122.031&user=peter

Data Provider

Currently, Local searching supports two data providers:

1. google places (provider=gp) default

2. poynt (provider=pt)

3. xad (provider=xad)

4. yellow page (provider=yp)

5. foursquare (provider=fs)

6. dianping (provider=dp) Only for China, system will check lat lng to determine the country

For default, all the following APIs will use Google Places as primary search provider,

 

Paging & Number of results

For all of the following APIs, you can add parameters

p={Positive integer}

(default is 1, The starting page for the search result.)

n={Positive integer}

(default is 10, The desired number of each call)

For example, to get the page 2, with 15 items.

Start a new search

U.S.:

Canada:

The above link will search pizza within the location lat=37.3323 and lng=-122.031,
Return all search results in xml/json, the result will also generate conversationId and searchId .

You will need the returned searchid and conversationId as it is a required parameter in subsequent calls.

<searchResult>
<conversationId>eea118e4-f441-4313-a842-d951da7f87af</conversationId>
<listing>
      <address>dsadsfa, Oakland, CA</address>
      <name>series 124 picture frames</name>
      <phone>4157626979</phone>
      <votedByMe>false</votedByMe>
      <votedByOther>false</votedByOther>
      ...
</listing>
<query>pizza</query>
<searchId>77012a62-b9cc-4cf4-9253-6953c09676af</searchId>
</searchResult>

Search the keyword, user name is mandatory.
Return all search results in xml/json
Search by keyword:

Search the keyword, user name is mandatory. Returns top 3 search results in html (this is specific to real-time version for now)
Search keywords:

Return a page with top 3 search results

  1. Pizza My Heart 1.07km
  2. Pizza Hut 1.22km
  3. Chuck E Cheese’s 1.37km

 

Location search with current lat/lng:

The input parameters lat and lng is for primary search.

If the additional parameters centerlat and centerlng are provided, the search will set the location as primary.

For example, search pizza in New York area.

if currently you are located at Broadway street, New York, (lat=40.7143528, lng=-74.0059731),
and you want to search in Long Island City, New York (centerlat=40.7615609, centerlng=-73.9750)

For each listing, the result contains two distance fields, sorting by distance:

<distance> is the distance of the lat & lng parameters.

<distanceToCenter> is the distance of the centerlat & centerlng parameters.

..
<listing>
<address>225 Park Row,New York,NY,10038</address>
<category>Pizza Restaurants</category>
<distance>0.20443017500963404</distance>
<distanceToCenter>1.720246018785119</distanceToCenter>
<id>35460</id>
<lat>40.713148</lat>
<listingType>ORGANIC</listingType>
<lng>-73.999746</lng>
...

Opentable reservations:

If the search result contains a restaurant that have the account with Opentable, the reservation link will be shown in <opentable_url>.

U.S

Canada:

...
   <listing>
      <address>49 E Main St,Patchogue,NY,11772</address>
      <category>Restaurants</category>
      <id>6410</id>
      <lat>40.765719</lat>
      <lng>-73.013871</lng>
      <name>Public House 49</name>
      <opentable_url>
          d.2ya.it/dre/api/rest/reserve/restaurant/71476?appId={AppID}&query=Public+House+49&lat=40.765962&lng=-73.013903&user=zia&searchid=null&cId=null
       </opentable_url>
       <phone>6315692767</phone>
       <pid>1</pid>
       <pretty_distance>0.03</pretty_distance>
       ...
    </listing>
...

Restaurant Search:

U.S, Canada:

Beijing, China: (System will check lat lng to determine its in China, using Dianping as data provider)

The query can be the restaurant name or any type of food.

To get a list of Cuisines (default – for google place, display in English)

<cuisines>
    <cuisine>
        <foodtype>Asian</foodtype>
        <displayorder>1</displayorder>
    </cuisine>
    <cuisine>
        <foodtype>Barbeque</foodtype>
        <displayorder>2</displayorder>
    </cuisine>
    <cuisine>
        <foodtype>Brazilian</foodtype>
        <displayorder>3</displayorder>
    </cuisine>
    <cuisine>
        <foodtype>Burgers</foodtype>
        <displayorder>4</displayorder>
    </cuisine>
    <cuisine>
        <foodtype>Mexican</foodtype>
        <displayorder>5</displayorder>
    </cuisine>
    <cuisine>
        <foodtype>Chinese</foodtype>
        <displayorder>6</displayorder>
    </cuisine>
    <cuisine>
        <foodtype>Desserts</foodtype>
        <displayorder>7</displayorder>
    </cuisine>
    <cuisine>
        <foodtype>Dim Sum</foodtype>
        <displayorder>8</displayorder>
     </cuisine>
    <cuisine>
        <foodtype>French</foodtype>
        <displayorder>9</displayorder>
    </cuisine>
    <cuisine>
        <foodtype>German</foodtype>
        <displayorder>10</displayorder>
    </cuisine>
    ...
</cuisines>

To get a list of Cuisines (for China provider, display in Chinese)

<cuisines>
<cuisine>
  <displayorder>1</displayorder>
  <foodtype>上海菜</foodtype>
  <countryid>CN</countryid>
</cuisine>
<cuisine>
  <displayorder>2</displayorder>
  <foodtype>北京菜</foodtype>
  <countryid>CN</countryid>
</cuisine>
<cuisine>
  <displayorder>3</displayorder>
  <foodtype>粤菜</foodtype>
  <countryid>CN</countryid>
</cuisine>
<cuisine>
  <displayorder>4</displayorder>
  <foodtype>川菜</foodtype>
  <countryid>CN</countryid>
</cuisine>
<cuisine>
  <displayorder>5</displayorder>
  <foodtype>蒙古菜</foodtype>
  <countryid>CN</countryid>
</cuisine>
<cuisine>
  <displayorder>6</displayorder>
  <foodtype>潮汕菜</foodtype>
  <countryid>CN</countryid>
</cuisine>
<cuisine>
  <displayorder>7</displayorder>
  <foodtype>客家菜</foodtype>
  <countryid>CN</countryid>
</cuisine>
...
</cuisines>

query is optional.
If query is not provided, result will be the general search for all type of restaurants.

Restaurant/Cafe/Bars Review:

For data provider xad (provider=xad), reviews will embed into the search result.

Restaurant search result from xad: (it comes with the reviews)

<more_info>
     <attribution type="desc">
          <text>DESCRIPTION by Citysearch</text>
     </attribution>
     <e_desc>Opened in 1897 at 53 Spring Street, just down the street from its present location, Lombardi's is one of the city's oldest eateries..</e_desc>
     <hrs>
          <display>Mon-Thu, 11:30am-11pm Fri-Sat, 11:30am-midnight Sun, 11:30-10pm</display>
     </hrs>
     <payment>
          <display>Cash~Check</display>
          <type>Cash</type>
          <type>Check</type>
     </payment>
     <cross_st>nr. Mott St.</cross_st>
     <all_reviews av_count="335" s_index="0" count="2">
          <reviews count="2">
               <review id="477775711">
                    <author>by Itellmymomthetruth at Citysearch</author>
                    <date>2011-09-24 15:12:05</date>
                    <rating>1.0</rating>
                    <title>Not very good</title>
                    <desc>I looked up on 2 websites for the best pizza in New York. If this is the best, I will never eat pizza in New York. It was bland and overpriced. If I was in New York and wanted a pizza, I would order from a national chain.On the debate between Chicago and New York, the Chicago pizza I ate at Pizza Due in Chicago whooped this pizzas butt. I grew up eating thin crust. The workers couldn't even tell me where to park. They need a lesson in cooking and customer relations. Don't go here.</desc>
               </review>
               <review id="387617771">
                    <author>by MaryTurner at Citysearch</author>
                    <date>2011-06-28 19:18:23</date>
                    <rating>5.0</rating>
                    <title>Best Pizza I've ever had in NYC</title>
                    <desc>Let me just get my only complaint about Lombardi's out of the way. The restaurant is very small and cramped and would not be appropriate for a large group of people. Their pizza is the best I've ever had, not just in NYC, and I've eaten a lot of pizza in my time. The sauce is zesty and a little sweet, and the crust is just slightly charred (not burnt, just a little black in spots, with a little crunch to it). Honestly, I don't even think toppings are necessary because the crust, sauce and cheese are so good. But to each his own, right? This place is as close to perfect as a pizzeria can get.</desc>
               </review>
          </reviews>
          <url type="r_next">
               <click>http://test.xad.com/rest/more_info?k=TPK-U3nKJpkcH-waIPhKejUtQRt30FRQ&uid=z&l_id=0Fmw3D%7E884110347%23103007108110%230%230%211%211%212%210%21NY%21US%21WEmw3D%210.0%210%7E1%7E0%7E1%7E%7E0%7E0&op=1&nr=2&nav=r_next&ri=2&o_fmt=xml&v=1.1</click>
          </url>
     </all_reviews>
     <url type="image">
          <click>http://images.citysearch.net/assets/imgdb/profile/36/a6/7108110p1.jpg</click>
     </url>
     <url type="map">
          <click>http://newyork.citysearch.com/profile/map/7108110/new_york_ny/lombardi_s.html</click>
     </url>
</more_info>

But for data provider yellowpage (provider=yp) or foursquare (provider=fs), reviews will NOT embed into the search result. You need to get details with the review.

Restaurant search result from yp or fs , it has NO reviews.

To get the reviews, please make a call to get restaurant detail, (see below section “Get listing by Id:“)

For example, retrieve Restaurant id #44962, the details information come with the reviews:

 

Restaurant/Cafe/Bars Photos:

Data provider foursquare provides some of the photos, by calling get-listing-details api:

http://d.2ya.it/dre/api/rest/listing/64342?appId={AppID}

See the multiple elements <listingphoto> :

<listing>
<address>124 E Main St.,Patchogue,NY,11772</address>
<category>Greek Restaurant</category>
<description/>
<distance>0.135</distance>
<distanceToCenter>0.0</distanceToCenter>
<id>64342</id>
<lat>40.76581901077894</lat>
<listingType>ORGANIC</listingType>
<listingphoto>

https://is0.4sqi.net/pix/wxJr5SVLr1rU7y0OrYfC-7GEtqaSNZWDnKuRP4d2xXI.jpg

</listingphoto>
<listingphoto>

https://is1.4sqi.net/pix/I545UNLEGGSEOLPK1DC5X5X2GF4H3CDDY5F1N4B3OPN01K2C.jpg

</listingphoto>
...

Cafe Search:

U.S, Canada:

Beijing, China: (System will check lat lng to determine its in China, using Dianping as data provider)

query is optional.. The query can be the cafe name.
If query is not provided, result will be the general search for cafe.

Bars Search:

U.S, Canada:

Beijing, China: (System will check lat lng to determine its in China, using Dianping as data provider)

query is optional.
The query can be the bars’ name.
If query is not provided, result will be the general search for bars.

Get listing by Id:

You can retrieve specific restaurant, cafe, bars, or local listing by ID.

for example, when you search

the results has the Id field in listing object:

<id>15530</id>

Then call this api to get it back:

By location, (Optional parameters lat and lng), the distance will be adjusted accordingly: