MenuMania Restaurant Search API
Overview:
The "MenuMania Restaurant Search API" allows the retrieval of MenuMania restaurant and review data based on a set of input parameters. This section outlines the various types of search operations that can be executed and provides example requests and responses.
This API can be used to add information regarding local restaurants, cafes and takeaways to your website, widget or mobile application.
Get a particular restaurant from the API
| Name | Data Type | Required / Optional | Description |
|---|---|---|---|
| listing_id | integer | optional | The MenuMania listing id that is returned in the API |
- Searching by Map Bounding Box
- Searching by Geo-Point and Radius
- Searching by Address and Suburb/City
- Narrowing Result Set By Category
- Narrowing Result Set By Cuisine
- Searching by Phone
- Response Values
- Response Codes
Search by Map Bounding Box:
Enables the retrieval of restaurant and review information based on a bounding box, defined by a Southwest latitude/longitude and a Northeast latitude/longitude geographic coordinate.
The bounding box format is defined as:
bounds=sw_latitude,sw_longitude|ne_latitude,ne_longitude
Input Parameters:
| sw_latitude | double | required | Southwest latitude of bounding box |
| sw_longitude | double | required | Southwest longitude of bounding box |
| ne_latitude | double | required | Northeast latitude of bounding box |
| ne_longitude | double | required | Northeast longitude of bounding box |
Sample Request:
http://www.menumania.co.nz/api/restaurant_review_search.php?bounds=-36.8621041,174.7503804|-36.8364660,174.7838398&mmwsid=XXXXXXXXXXXXXX
Sample Response Search by Geo-Point and Radius:
Enables searching for restaurant and review information within a certain radius of a particular location.
Input Parameters:
| Name | Data Type | Required / Optional | Description |
|---|---|---|---|
| term | string | optional | String representing the name of restaurant or search term being requested. (E.G. "thai", "cafe") |
| num_biz_requested | integer | optional | Specifies the number of restaurants to return in the result set. Default is 10. Minimum value is 1 and maximum value is 20 |
| lat | double | required | Latitude of geo-point to search near |
| lon | double | required | Longitude of geo-point to search near |
| radius | double | optional | Radius to use while searching around specified geo-point. Maximum value = 20. If a radius is not specified, 5 will be set as default value |
Sample Request:
http://www.menumania.co.nz/api/restaurant_review_search.php?term=thai&lat=-36.878544&lon=174.727966&radius=5&num_biz_requested=10&mmwsid=XXXXXXXXXXXXXX
Sample Response Search by Suburb, Address and City:
Enables searching for restaurant and review information based on a particular suburb, address or city.
Input Parameters:
| Name | Data Type | Required / Optional | Description |
|---|---|---|---|
| term | string | optional | String representing the name of restaurant or search term being requested (E.G. "invito cafe") |
| num_biz_requested | integer | optional | Specifies the number of restaurants to return in the result set. Default is 10. Minimum value is 1 and maximum value is 20 |
| location | string | required | Specifies the combination of "address, suburb, city" to be used when searching for restaurants |
| radius | double | optional | Radius to use while searching around specified geo-point. Maximum value = 20. If a radius is not specified, it will be chosen based on the specificity of the location |
Sample Request:
http://www.menumania.co.nz/api/restaurant_review_search.php?term=steak&location=150%20Queen%20St%2CAuckland%20City&mmwsid=XXXXXXXXXXXXXX
Sample Response Narrowing Result Set By Category:
All result sets returned via the MenuMania Restaurant Search API can be narrowed to only include places that fall under a particular category or venue type.
Input Parameters:
| Name | Data Type | Required / Optional | Description |
|---|---|---|---|
| category | string | optional | This parameter allows filtering of result set by a particular category. You can search in multiple categories by separating them with a plus character, (E.G. category=restaurants+cafes) |
A full list of supported categories is available here.
Sample Request:
http://www.menumania.co.nz/api/restaurant_review_search.php?category=restaurants&location=150%20Queen%20St%2CAuckland%20City&mmwsid=XXXXXXXXXXXXXX
Sample Response Narrowing Result Set By Cuisine:
All result sets returned via the MenuMania Restaurant Search API can be narrowed to only include restaurants that fall under a particular cuisine type.
Input Parameters:
| Name | Data Type | Required / Optional | Description |
|---|---|---|---|
| cuisine | string | optional | This parameter allows filtering of result set by a particular cuisine. You can search in multiple cuisines by separating them with a plus character, (E.G. cuisine=thai+indian) |
A full list of supported cuisines is available here.
Sample Request:
http://www.menumania.co.nz/api/restaurant_review_search.php?cuisine=thai&location=150%20Queen%20St%2CAuckland%20City&mmwsid=XXXXXXXXXXXXXX
Sample Response
Search by Phone:
Enables the retrieval of restaurant information based on a phone number input parameter. If the phone number provided matches a restaurant in the MenuMania system, restaurant and review information will be returned.
Input Parameters:
| Name | Data Type | Required / Optional | Description |
|---|---|---|---|
| phone | integer | optional | Parameter that specifies the restaurant 9-digit phone number to search for |
Sample Request:
http://www.menumania.co.nz/api/restaurant_review_search.php?phone=123456789&mmwsid=XXXXXXXXXXXXXX
Sample Response
Response Values:
This section outlines the response values from a "restaurant_review_search" operation.
| Node Element | Type | Definition | Max Number In Result Set |
|---|---|---|---|
| restaurants | list | node that contains a list of restaurant entries | 1 |
| address1 | node | line one of restaurant address | 1 per restaurant |
| address2 | node | line two of restaurant address | 1 per restaurant |
| categories | list | provides a list of categories/venue types that this restaurant is associated with | 2 per restaurant |
| categories.category_filter | node | filter name for this particular category | unbounded |
| categories.category_name | node | display name for a particular category | unbounded |
| cuisines | list | provides a list of cuisines that this restaurant is associated with | 2 per restaurant |
| cuisines.cuisine_filter | node | filter name for this particular cuisine | unbounded |
| cuisines.cuisine_name | node | display name for a particular cuisine | unbounded |
| cuisines.search_url | node | URL to execute a search for this particular cuisine type on MenuMania.co.nz | unbounded |
| suburb | node | name of suburb/town that restaurant is located in | 1 per restaurant |
| city | node | name of city that restaurant is located in | 1 per restaurant |
| id | node | MenuMania ID for this restaurant | 1 per restaurant |
| is_closed | node | boolean, true if the restaurant is closed | 1 per restaurant |
| latitude | node | latitude of restaurant | 1 per restaurant |
| longitude | node | longitude of restaurant | 1 per restaurant |
| mobile_url | node | URL for mobile restaurant page on MenuMania | 1 per restaurant |
| name | node | name of restaurant | 1 per restaurant |
| nearby_url | node | URL to execute search for nearby restaurants | 1 per restaurant |
| suburbs | list | List that provides suburb(s) information for restaurant | 1 per restaurant |
| suburbs.name | node | Name of suburb to which this restaurant belongs | unbounded |
| suburbs.url | node | URL to execute a search for that suburb on MenuMania | unbounded |
| phone | node | phone number for this restaurant | 1 per restaurant |
| photo_thumb_url | node | URL to thumbnail photo for this restaurant | 1 per restaurant |
| photo_small_url | node | URL to small photo for this restaurant | 1 per restaurant |
| avg_rating | node | Numeric value representing the average review for this restaurant | 1 per restaurant |
| rating_img_url | node | URL to star rating image for this restaurant | 1 per restaurant |
| rating_img_url_small | node | URL to small version of rating image for this restaurant | 1 per restaurant |
| review_count | node | Number of reviews associated with this restaurant | 1 per restaurant |
| reviews | list | Contains a list of 3 reviews associated with this restaurant | 1 per restaurant |
| reviews.id | node | MenuMania ID for this review | 1 per review |
| reviews.text_excerpt | node | Excerpt of review text | 1 per review |
| reviews.url | node | URL to restaurant profile page with this review selected | 1 per review |
| reviews.user_name | node | Name of user that created review | 1 per review |
| reviews.user_photo_url | node | URL to photo of the user that created review | 1 per review |
| reviews.user_photo_url_small | node | URL to small photo of the user that created review | 1 per review |
| reviews.user_url | node | URL of user's profile page (photo must link to this URL) | 1 per review |
| reviews.rating | node | Numeric value representing the rating of this review | 1 per review |
| reviews.rating_img_url | node | URL to star rating image for this review | 1 per review |
| reviews.mobile_uri | node | URL for mobile restaurant page with this review selected | 1 per review |
| reviews.date | node | Date review was written, in format (YYYY-MM-DD). | 1 per review |
| region | node | Region that this restaurant is located in | 1 per restaurant |
| attributes | list | Contains a list of attribute information associated with this restaurant | 1 per restaurant |
| attributes.url | node | URL to restaurant listing page on MenuMania | 1 per restaurant |
| attributes.menu_url | node | URL to restaurant menu information to display on your site in an IFRAME on a popup window. Click here for an example. | 1 per restaurant |
| postal code | node | Postal code for this restaurant | 1 per restaurant |
| message | list | Contains meta data about request | 1 |
| message.text | node | Message describing response code | 1 |
| message.code | node | Numeric code indicating whether response was generated correctly or not | 1 |
Response Codes:
This section outlines the response codes that can be expected from a "restaurant_review_search" operation
| Response Code | Response Message | Description |
|---|---|---|
| 0 | OK | Indicates the request completed without error |
| 1 | Server error | Indicates that a system error occurred and that the request was unable to be processed |
| 2 | Invalid MMWSID | Returned when an invalid MMWSID is supplied with the API request |
| 3 | Missing MMWSID | Indicates that the required MMWSID parameter was not supplied with the request |
| 4 | Exceed daily API request limit | Returned when the number of requests executed for a particular MMWSID on a particular day exceeds the specified limit |
| 5 | API Unavailable | Indicates that the MenuMania API is currently not available |
| 6 | Did not understand query | Indicates an invalid API request was sent |
| 7 | Unspecified location | Not enough information was provided in the request to allow MenuMania to determine a specific search location |
| 8 | Bad term parameter | The term parameter provided in the request could not be understood |
| 9 | Bad location parameter | The location parameter provided in the request could not be understood |
| 10 | Area too large | Indicates that the geographical area is too large for this search request. Max search area is 20km |
| 11 | Unknown category | Indicates that an unknown category/venue type was specified |
| 12 | Unknown cuisine | Indicates that an unknown cuisine was specified |
| 13 | No record found | Indicates that the request returned no records |
| 14 | Invalid phone number | Indicates that the value of the "phone" parameter was not a valid 9-digit telephone number |
Sample Responses:
This section provides a sample response for a "RestaurantReviewSearch" operation in XML and JSON output.
XML:
<?xml version="1.0" encoding="UTF-8"?>
<listings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<listing>
<id>61</id>
<is_closed>False</is_closed>
<name>Gina's Pizza & Pasta Bar</name>
<address1>209 Symonds St</address1>
<address2></address2>
<suburb>Auckland Central</suburb>
<city>Auckland City</city>
<country>NZ</country>
<latitude>-36.863537</latitude>
<longitude>174.760818</longitude>
<mobile_url>http://m.menumania.co.nz/restaurants/ginas-pizza-pasta-bar</mobile_url>
<phone>09 302 2061</phone>
<photo_thumb_url>http://www.menumania.co.nz/mm-data/media/HjN2sgNIGHamSp7BbjpU-100x100.jpg</photo_thumb_url>
<photo_small_url>http://www.menumania.co.nz/mm-data/media/HjN2sgNIGHamSp7BbjpU-46x46.jpg</photo_small_url>
<categories>
<category>
<category_filter>italian</category_filter>
<category_name>Italian</category_name>
</category>
<category>
<category_filter>pizza</category_filter>
<category_name>Pizza</category_name>
</category>
</categories>
<cuisines>
<cuisine>
<cuisine_filter>italian</cuisine_filter>
<cuisine_name>Italian</cuisine_name>
</cuisine>
<cuisine>
<cuisine_filter>pizza</cuisine_filter>
<cuisine_name>Pizza</cuisine_name>
</cuisine>
</cuisines>
<review_count>5</review_count>
<avg_rating>3</avg_rating>
<rating_img_url>http://www.menumania.co.nz/img/stars/stars_3.png</rating_img_url>
<rating_img_url_small>http://www.menumania.co.nz/img/stars/stars_small_3.png</rating_img_url_small>
<reviews>
<review>
<rating name="stars">5</rating>
<rating_img_url>http://www.menumania.co.nz/img/stars/stars_5.png</rating_img_url>
<rating_img_url_small>http://www.menumania.co.nz/img/stars/stars_small_5.png</rating_img_url_small>
<text_excerpt>best italian place for fun fun fun meals! esp for celebrations! best recommended for chicks only nites ;) really beautiful...</text_excerpt>
<url>http://www.menumania.co.nz/restaurants/ginas-pizza-pasta-bar#review-426</url>
<user_name>chickie</user_name>
<user_photo_url_small>http://www.gravatar.com/avatar/20fbc4faa4239ec33879a5fe627df47a?s=32&d=identicon&r=G</user_photo_url_small>
</review>
<review>
<rating name="stars">5</rating>
<rating_img_url>http://www.menumania.co.nz/img/stars/stars_5.png</rating_img_url>
<rating_img_url_small>http://www.menumania.co.nz/img/stars/stars_small_5.png</rating_img_url_small>
<text_excerpt>Awsome atmosphere, fantastic food. Always full so make sure you book a day in advance.</text_excerpt>
<url>http://www.menumania.co.nz/restaurants/ginas-pizza-pasta-bar#review-182</url>
<user_name>Nick M.</user_name>
<user_photo_url_small>http://www.gravatar.com/avatar/29614e56c49975979e0580082f293df9?s=32&d=identicon&r=G</user_photo_url_small>
<user_url>http://www.menumania.co.nz/user_details?userid=354</user_url>
</review>
<review>
<rating name="stars">1</rating>
<rating_img_url>http://www.menumania.co.nz/img/stars/stars_1.png</rating_img_url>
<rating_img_url_small>http://www.menumania.co.nz/img/stars/stars_small_1.png</rating_img_url_small>
<text_excerpt>Gina,s mmm overated excellent marketing by having hot waiters serving food food verges on something you could cook better at home...</text_excerpt>
<url>http://www.menumania.co.nz/restaurants/ginas-pizza-pasta-bar#review-4649</url>
<user_name>andrew symons</user_name>
<user_photo_url_small>http://www.gravatar.com/avatar/29102bd58947aaeeb2dcc594ced590f4?s=32&d=identicon&r=G</user_photo_url_small>
</review>
</reviews>
<attributes>
<url>http://www.menumania.co.nz/restaurants/ginas-pizza-pasta-bar</url>
<menu_url>http://www.menumania.co.nz/api/menupartner.php?partner=10&bizid=9999&t=1234569455&auth=m7NeCQOAnCu3femlHa2ZJnWbCA139Yia</menu_url>
</attributes>
</listing>
<message>
<code>0</code>
<text>OK</text>
<version>1.0</version>
</message>
</listings> JSON:
{"listings": [{"address1": "209 Symonds St",
"address2": "",
"avg_rating": 3,
"categories": [{"category_filter": "italian",
"category_name":"Italian"},
{"category_filter": "pizza",
"category_name": "Pizza"}],
"cuisines": [{"cuisine_filter": "italian",
"cuisine_name":"Italian"},
{"cuisine_filter": "pizza",
"cuisine_name": "Pizza"}],
"suburb": "Auckland Central",
"city": "Auckland City",
"id": "61",
"is_closed": False,
"latitude": "-36.863537",
"longitude": "174.760818",
"mobile_url": "http://m.menumania.co.nz/restaurants/ginas-pizza-pasta-bar",
"name": "Gina's Pizza & Pasta Bar",
"phone": "09-302 2061",
"photo_thumb_url": "http:\/\/www.menumania.co.nz\/mm-data\/media\/HjN2sgNIGHamSp7BbjpU-100x100.jpg",
"photo_small_url": "http:\/\/www.menumania.co.nz\/mm-data\/media\/HjN2sgNIGHamSp7BbjpU-46x46.jpg",
"rating_img_url": "http:\/\/www.menumania.co.nz\/img\/stars\/stars_3.png",
"rating_img_url_small": "http:\/\/www.menumania.co.nz\/img\/stars\/stars_small_3.png",
"review_count": "5",
"reviews": [{"id": "426",
"rating": "5",
"rating_img_url": "http:\/\/www.menumania.co.nz\/img\/stars\/stars_3.png",
"rating_img_url_small": "http:\/\/www.menumania.co.nz\/img\/stars\/stars_small_3.png",
"text_excerpt": "best italian place for fun fun fun meals! esp for celebrations!\r\nbest recommended for chicks only nites ;)\r\nreally beautiful...",
"url": "http:\/\/www.menumania.co.nz\/restaurants\/ginas-pizza-pasta-bar",
"user_name": "chickie",
"user_photo_url_small": "http:\/\/www.gravatar.com\/avatar\/20fbc4faa4239ec33879a5fe627df47a?s=32&d=identicon&r=G",
"user_url": ""},
{"id": "182",
"rating": "5",
"rating_img_url": "http:\/\/www.menumania.co.nz\/img\/stars\/stars_3.png",
"rating_img_url_small": "http:\/\/www.menumania.co.nz\/img\/stars\/stars_small_3.png",
"text_excerpt": "Awsome atmosphere, fantastic food. Always full so make sure you book a day in advance.",
"url": "http:\/\/www.menumania.co.nz\/restaurants\/ginas-pizza-pasta-bar",
"user_name": "Nick M.",
"user_photo_url_small": "http:\/\/www.gravatar.com\/avatar\/29614e56c49975979e0580082f293df9?s=32&d=identicon&r=G",
"user_url": "http:\/\/www.menumania.co.nz\/user_details?userid=354"},
{"id": "4649",
"rating": "1",
"rating_img_url": "http:\/\/www.menumania.co.nz\/img\/stars\/stars_3.png",
"rating_img_url_small": "http:\/\/www.menumania.co.nz\/img\/stars\/stars_small_3.png",
"text_excerpt": "Gina,s mmm overated excellent marketing by having hot waiters serving food food verges on something you could cook better at home...",
"url": "http:\/\/www.menumania.co.nz\/restaurants\/ginas-pizza-pasta-bar",
"user_name": "andrew symons",
"user_photo_url_small": "http:\/\/www.gravatar.com\/avatar\/29102bd58947aaeeb2dcc594ced590f4?s=32&d=identicon&r=G",
"user_url": ""}],
"attributes":{"url":"http:\/\/www.menumania.co.nz\/restaurants\/invito-cafe",
"menu_url":"http:\/\/www.menumania.co.nz\/api\/menupartner.php?partner=10&bizid=9999&t=1234569455&auth=m7NeCQOAnCu3femlHa2ZJnWbCA139Yia"}}],
"message": {"code": 0, "text": "OK", "version": "1.0"}}