YelloYello Api

YelloYello offers partners a full features REST JSON API.

For API access email



All requests are expected to be UTF-8 encoding.


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


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

Authorization: Token YOUR_API_KEY


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



Places are the base of listings on YelloYello.


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
website The website address
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.


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


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'


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



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
  "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"],
  "meta": {
    "pagination": {
      "current_page": 1,
      "next_page": 2,
      "prev_page": null,
      "total_pages": 2,
      "total_count": 33

GET /places/[slug].json

      "name":"Dong Hae Korean Grill \u0026 Dong Hae Korean Grill \u0026 Sushi",
      url: "",
      "street":"North 1st Avenue",
         "free parking",
         "Asian Restaurant",
            "name":"Asian Restaurant",

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.


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] = ""
  place[listings_attribtues][1][url] = ""

PATCH /places/[slug].json

DELETE /places/[slug].json

You can delete/destroy only your own Places.



GET /categories.json

Published on July 09, 2015 14:06