YelloYello Api

YelloYello offers partners a full features REST JSON API.

For API access email info@yelloyello.com.

Basics

Encoding

All requests are expected to be UTF-8 encoding.

Versioning

Versioning is done based uppon the endpoint url. We currently have a single version of the API: v1.

http://www.yelloyello.com/api/[version]

Authentication

We use HTTP token authentication. You can by adding a HTTP header such as:

Authorization: Token YOUR_API_KEY

Pagination

Default resource pagination is done via the page and per parameters.

Resources

Places

Places are the base of listings on YelloYello.

Attributes

Places have the following attributes (marked with a * are required):

Attribute Description Example
name* The name of the listing My business
full_address The full address of the listing My street 12, City, US
address_supplement An extra to the address Unit 12
phone The phone number 055-12341234
fax The fax number 055-12341235
mobile The mobile phone number 06-12341235
email The email address info@mybusiness.com
website The website address www.mybusiness.com
details Full (multi-line) description or about text of the listing We're founded in 2012 and would love to help you with ..
listings_attributes An array of Listing objects
photos_attributes An array of Photo objects
category_names An array of Category names (strings). We map those to our own categories.

Listing

Listings are relevant mentions of the Place around the web. This might be a link to a Facebook, Twitter, Linkedin, Pinterest, etc. page or their OpenTable reservation page or a iTunes App store link.

Attribute Description Example
url The url of the listing http://www.facebook.com/mybizpage

Category

Categories simply categorize Places. We store many different category types. Those get mapped to the YelloYello category system (which we try to keep similar to the Facebook Page categories since those are pretty complete). Only the mapped categories are shown on the Listing page.

Attribute Description Example
name The name of the Category 'Restaurant', 'Plumber' or 'Asian Restaurant'

Photo

Photos are image objects that are stored on the YelloYello CDN.

Attribute Description Example
file The image file Multipart
file_remote_url The url of an image https://www.google.com/images/srpr/logo11w.png

Endpoints

Places

GET /places/search.json

Parameter Description
search[q] Query, the general full text terms to match
search[l] Location to search nearby. Eg. "@lat,lng"
page The page number
/api/v1/places/search?search[q]=Arent
{
  "places": [
    {
      "slug": "12e-montessorischool-amsterdam",
      "name": "12e Montessorischool",
      "street": "Arent Janszoon Ernststraat",
      "street_number": "130",
      "zip": "1082LP",
      "city": "Amsterdam",
      "state": "Noord-Holland",
      "country_code": "NL",
      "lat": "52.33203",
      "lng": "4.87573",
      "phone": "31206442076",
      "mobile": null,
      "fax": "31204421017",
      "email": null,
      "website": null,
      "rating": null,
      "reviews_count": 0,
      "photos_count": 0,
      "tag_list": ["education","training","primary education"],
      "category_names": ["Asian Restaurant","Restaurant"],
      "details":null
    },
    ..
  ],
  "meta": {
    "pagination": {
      "current_page": 1,
      "next_page": 2,
      "prev_page": null,
      "total_pages": 2,
      "total_count": 33
    }
  }
}

GET /places/[slug].json

/api/v1/places/12e-montessorischool-amsterdam.json
{
   "place":{
      "slug":"dong-hae-korean-grill-dong-hae-korean-grill-sushi-minneapolis",
      "name":"Dong Hae Korean Grill \u0026 Dong Hae Korean Grill \u0026 Sushi",
      url: "http://www.yelloyello.com/places/dong-hae-korean-grill-dong-hae-korean-grill-sushi-minneapolis",
      "street":"North 1st Avenue",
      "street_number":"251",
      "zip":"55401",
      "city":"Minneapolis",
      "state":"Minnesota",
      "country_code":"US",
      "lat":"44.982184",
      "lng":"-93.270961",
      "phone":"+16123331999",
      "mobile":null,
      "fax":null,
      "email":"",
      "website":"http://www.donghaeres.com",
      "rating":"4.5",
      "reviews_count":2,
      "photos_count":2,
      "tag_list":[
         "free parking",
         "restaurant",
         "visa"
      ],
      "category_names":[
         "Asian Restaurant",
         "Restaurant"
      ],
      "details":"",
      "categories":[
         {
            "id":1198,
            "name":"Asian Restaurant",
            "type":"FacebookPageCategory"
         },
         {
            "id":763,
            "name":"Restaurant",
            "type":"FacebookPageCategory"
         }
      ],
      "photos":[
         {
            "id":11581,
            "thumb_url":"http://cdn.yelloyello.com.s3.amazonaws.com/photos/581/11581/thumb_87657.jpg",
            "medium_url":"http://cdn.yelloyello.com.s3.amazonaws.com/photos/581/11581/medium_87657.jpg",
            "large_url":"http://cdn.yelloyello.com.s3.amazonaws.com/photos/581/11581/large_87657.jpg",
            "content_type":"image/jpeg"
         },
         {
            "id":78320,
            "thumb_url":"http://cdn.yelloyello.com.s3.amazonaws.com/photos/320/78320/thumb_logo11w.png",
            "medium_url":"http://cdn.yelloyello.com.s3.amazonaws.com/photos/320/78320/medium_logo11w.png",
            "large_url":"http://cdn.yelloyello.com.s3.amazonaws.com/photos/320/78320/large_logo11w.png",
            "content_type":"image/png"
         }
      ]
   }
}

POST /places.json

When submitting category_names, photos_attributes, etc. make sure you pass them as an Array place[category_names][]. You can also use a numbered Array to specify multiple attributes on each object.

/api/v1/places.json

Example payload (send as HTTP POST attributes):

  place[name] = "12e Montessorischool"
  place[full_address] = "Arent Janszoon Ernststraat 130, 1082LP, Amsterdam"
  place[phone] = "020-6442076"
  place[fax] = "020-4421017"
  place[category_names][] = "Restaurant"
  place[photos_attributes][0][file] = [encoded file]
  place[photos_attributes][1][file_remote_url] = "http://www.some.image/url"
  place[listings_attribtues][0][url] = "http://facebook.com/yourbusiness"
  place[listings_attribtues][1][url] = "http://yelp.com/biz/yourbusiness"

PATCH /places/[slug].json

DELETE /places/[slug].json

You can delete/destroy only your own Places.

/api/v1/places/12e-montessorischool-amsterdam.json

Categories

GET /categories.json

/api/v1/categories.json?page=1&per=100
Published on July 09, 2015 14:06