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 |
| 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