/restaurant/list

Returns restaurant list of pizzerias near given address.

Request

This includes restaurants within 5 kilometers or restaurants that delivers to given address.

By address

When searching by address, restaurants are searched by certain radius around the address. The radius is by default 5 kilometers, that means, that by default restaurants that are at most in 5 kilometer away from the address will be returned.

POST nameValueRequired?
address"Funny address 1"Yes
postal_code"01234"No
city"TestCity"Yes
radius5No
chain_id1No
sort_by"distance"No
cuisinestrueNo

By coordinates

When working with mobile platforms or other platforms that contains GPS chip, getting coordinates of the customer is virtually easy. Those coordinates can be used to return restaurants around customer in similar manner with address based search.

POST nameValueRequired?
latitude60.403415Yes
longitude25.104618Yes
radius5No
chain_id1No
sort_by"distance"No
cuisinestrueNo

By city name

If customer knows that she wants to order from a restaurant in certain city but doesn’t know any address close to it, inserting city name to return all restaurants in a city may be viable option.

In such case customer can just insert city name and request all restaurants of the city. If there is a form that contains address, city, postal code, this request could be (and is) automatically done, instead of request based filtering. If the client wants to restrict this method out, client side validation that all necessary fields is present is the way.

This list will be very long for Helsinki and other cities that has many restaurants.

POST nameValueRequired?
city"Helsinki"Yes
chain_id1No
cuisinestrueNo

By restaurant name

Sometimes customer knows specific restaurant name or part of it. This action can be used to search restaurants by name.

POST nameValueRequired?
restaurant_name"demo"Yes
chain_id1No
cuisinestrueNo

By postal code

Some people prefers to use only postal code for searching restaurants. Due technical limits, it may be either more or less accurate than searching with city name only. For example for Helsinki, it would be more accurate though. The most accurate method to search restaurants is full address search.

POST nameValueRequired?
postal_code"04250"Yes
chain_id1No
cuisinestrueNo

Notes

Response

[
  {
    "comment":"Restaurant’s unique id, used in future queries to specify the restaurant for data fetching and order creation",
    "restaurant_id":"774",
    "name":"Demo Testi kauppa",
    "address":"Kauppakaari 15",
    "postal_code":"04200",
    "city":"Kerava",

    "comment":"In numeric format, without any dashes or spaces (string, not int)",
    "phone_number":"0505640847",
    "latitude":"60.403671",
    "longitude":"25.098875",

    "comment":"A decimal from 1 to 5, where 1 is lowest and 5 highest. Average of all ratings given to restaurant.",
    "rating":3.9269277845777,

    "comment":"Amount of reviews done to this restaurant",
    "rating_count":50436,

    "comment":"Pizzeria’s URL, can be used to show pizzeria’s home page",
    "url":"pizzaonline.pizzaonline.fi",

    "comment":"Whether restaurant is a premium restaurant. See section below for more information",
    "has_premium":true,

    "comment":"If restaurant has given a diploma, this number tells which of them restaurant has",
    "diploma":"2500",

    "comment":"If restaurant offers bonus from orders, this value shows the amount of bonus in percent. If zero, restaurant does not give bonus",
    "bonus_percent":"15",

    "comment":"If zero, it means unlimited.",
    "delivery_range":"10.00",

    "comment":"If restaurant belongs to a chain, this attribute is set. Zero if doesn’t belong to.",
    "chain_id":"0",

    "comment":"Distance in kilometers between location given as input and this restaurant",
    "distance":"5.3",

    "comment":"Base url which can be used to get restaurant’s image data. See Image section below for description.",
    "image_base_url":"https://static.slm.fi/image_path",

    "comment":"Timetable is better described at /documentation/restaurant_timetable page. Please see the values and comments at there",
    "timetable":{
      ".."
    },

    "comment":"List of food types this restaurant provides. Included only if cuisines variable in the request is true.",
    "cuisines":{
      "Names", "Of", "Nice", "And", "Yummy", "Cuisines"
    }
  },

  ".."
]

Timetable and restaurant statuses

They are found from /restaurant/timetable page.

Premium restaurants

In Fiidmi network there is certain restaurants that have premium status. These restaurants are recommended by Fiidmi, so they should be shown before other restaurants, maybe with some kind of emphasis.

You can see Pizzaonline’s way to implement this here.

Diplomas

A restaurant may have been awarded with a diploma for delivering certain amount of orders through Fiidmi network. These diplomas are awarded at certain levels, like 2500, 5000, 7500, 10000 and so on. If restaurant does not have any diploma awarded, it has 0 in diploma field of this listing.

Chains

There is some restaurant chains, like Kotipizza. For exaple, if you want to filter to only Kotipizza restaurants, you could loop through the restaurant list and take only restaurants where chain id is Kotipizza’s.

Distance

The distance parameter in result is for information purposes only; if you have another service you can use to get more accurate data, you should use it instead of this action’s distance related functionality.

Distance won’t be in when searching by city name and /customer/restaurants/list, because there is no way to know distance between customer and restaurants in city, so sorting by distance won’t work either.

Restaurant related images

The API returns image_base_url attribute, which contains base path which client can use to get actual image data. Size of images are undefined, hence the client should specify width parameter to let our client to do the scaling.

Construction of the url is {image_base_url}/{category}/{type}.

image_base_url is API response’s image_base_url, category is either logo or banner and type is either default or random. If you’d want to get random logo of a restaurant, you’d use following url: {image_base_url}/logo/random

There is parameter width which can be appended to the image url. It takes width of the image in pixels as argument. For example {image_url}?width=10001 to get an image with width of 10001.

Categories

The available category types logo and banner defines restaurant’s logo and “header” image of the restaurant, respectively.

Types

The available types default and random tells that either default image or image from a pool of images will be returned.

Expectable errors

See error conventions section for explanation how error system works.

Label Additional data Description
NO_RESTAURANTS_FOUNDNoneThere is no restaurants near to customer. There is a possibility to get restaurant in the city with searching only by city name, but those other restaurants most likely won’t do a deliveries to the address. Some does, though, deliver more than default 5 kilometer range.
INVALID_ADDRESSNoneIf the ”identifier” is 2, it means that we don’t know any restaurants that delivers to this address. Otherwise, the postal code is invalid.
INVALID_CHAIN_IDNoneMake sure it’s correct chain id.
INVALID_RADIUSNoneMake sure it’s correct radius.
LOCATOR_BACKEND_FAILEDurlIf there was problem with operating with backend, this is thrown. Should be handled.
COORDINATES_CONVERSION_ERRORNoneThere should be some some other errors; this is just catch-all.
INVALID_POSTAL_CODENoneIf you’re searching only by postal code and insert invalid postal code, this is returned.