/restaurant/metadata

This action can be used fetch basic data of restaurant.

Generally, /restaurant/get is used to retrieve all data related to a restaurant. In some cases, particularly with lightweight websites, implementing local storage to store and handle data of returned by /restaurant/get is too much, this action can be used to fetch this data on demand.

Request structure

The structure is following:

POST nameValueRequired?
restaurant_idintegerYes
languagestringNo
delivery_methodsbooleanNo

Usage of this language attribute is described at /account/register’s language section.

delivery_methods is optional parameter which returns raw delivery method data for client to use. Easy way to handle delivery support for restaurants is /restaurant/delivery_methods action. See below for more information.

Response

Comments visible in snippet below does not exist in real responses.

{
  "id":"774",
  "name":"Demo Testi kauppa",
  "regular_cash_enabled":"Whether restaurant does not allow cash orders but for regular customers. See separate section",
  "address":{
    "address":"Kauppakaari 15",
    "phone_number":"0451110007",
    "postal_code":"04200",
    "city":"Kerava",
    "latitude":"60.403671",
    "longitude":"25.098875"
  },
  "comment":"Hash of payment methods, where id is payment method’s id and hash as a value that contains a name and slug",
  "payment_methods":{
    [
      "id":{
        "comment":"This should be shown to customer when showing payment methods in a listing, for example",
        "name":"Payment Method Name",
        "comment":"This is uniformed identifier for this payment method across networks in Fiidmi system. Not used in API at the moment.",
        "slug":"payment_slug",
        "comment":"Additional cost that using of a payment method costs to user.",
        "cost":0.15,
        "comment":"Additional percent that using of a payment method costs to user. For example with total price (minus delivery price)
        of 10 euros, with 2,5 % cost, there is 0,25 euros extra cost applied on top of the order. In case 'cost' is also set, it needs to be applied before percent.",
        "percent":2.5
      },
      "another_id":{
        ".. more payment methods .."
      }
    ],
  },

  "comment":"average time a delivery order might take. Restaurants may send additional message to customer telling",
  "comment":"more close estimate time, but this time is default estimate for delivery.",
  "average_delivery_time":"50",
  "comment":"Same for fetch (takeaway) orders",
  "average_fetch_time":"20",

  "comment":"How much extra making an order will cost for orders with total sum under small_order_fee_limit.",
  "small_order_additional_fee":"10.00",

  "comment":"If order’s total sum (in euros) is below this, there is need for extra fee determined by small_order_additional_fee. If 0.00, no limit is used.",
  "small_order_fee_limit":"10.00",

  "comment":"describes if the restaurant has a takeaway possibility.",
  "has_takeaway":"1",

  "comment":"radius in kilometers of the area restaurant makes deliveries. if zero, it means unlimited",
  "delivery_range":"5.00",

  "comment":"Determines how many ingredients of a product can be changed to another.
  For example, if this is 2 and product has 4 changeable ingredients, two of them (at most) can be changed to other ingredients.
  0 means unlimited changes.",
  "changeable_ingredients_amount":"2",

  "comment":"This status is used to determine whether restaurant should be shown in public listings (/restaurant/list).
  Because restaurants that have available = 0 are filtered out from /restaurant/list by default, this attribute does not
  need handling.",
  "available":"1",

  "comment":"if lunch prices applies only to local orders or to orders made through API too. If this is 1, they applies
  to online orders too.",
  "lunch_price_in_online_orders":1,

  "comment":"this field is optional and set only few of restaurants.",
  "description":"Hardly ever present description of restaurant",

  "comment":"See Delivery methods section below",
  "delivery_methods":[
    {
      "comment":"Id of the delivery method. This is what is given as delivery method in /restaurant/make_order.",
      "id":"1",

      "comment":"A name of the delivery method that can be shown to the customer.",
      "name":"funky delivery method",

      "zones":[
        {
          "comment":"price of the delivery if zone matches",
          "price":"4.00",

          "comment":"start length of area in kilometers to point further from restaurant",
          "start_radius":"0.00",

          "comment":"end length of area in kilometers to point further from restaurant",
          "end_radius":"2.00",

          "comment":"If this is zero, delivery is never free. Otherwise the delivery price is not used if the total price is at least this amount.",
          "free_delivery_limit":"12.50",

          "comment":"If total price of the order is smaller than this limit, customer can’t use this zone.",
          "delivery_possible_limit":"1.99",

          "comment":"Distance in kilometers. Calculated distance between given address and the restaurant. This is mainly useful for visual information, if user’s address is not accurate.",
          "distance":"5.32"
        },
        {
          "price":"6.00",
          "start_radius":"2.00",
          "end_radius":"5.00",
          "free_delivery_limit":"12.50",
          "delivery_possible_limit":"1.99",
          "distance":"5.32"
        },
      ],
      "times":[
        {
          "comment":"Start time in readable representation.",
          "start_time":"09.30",

          "comment":"start time for this zone in seconds from midnight. Example time is 08:00 at morning.",
          "start_time_seconds":"28800",

          "comment":"End time in readable representation. If this time is lower than start time, it means the time will go over midnight. For example 05.00 would mean 5 at next day’s morning.",

          "comment":"end time for this zone in seconds from midnight. Times can go over 24:00, when the times will be 24 hours + time of clock. Example time is 05:00 past midnight.",
          "end_time_seconds":"104400",

          "comment":"week day as integer (1-7). 1 is monday and 7 sunday.",
          "weekday":"1",

          "comment":"If this is zero, additional_price needs to be applied on top of delivery price all the time. Otherwise the additional_price is not applied to order’s delivery price if the total price is at least this amount.",
          "free_delivery_limit":"12.50",

          "comment":"price to be added to delivery_fee or zone’s delivery fee",
          "additional_price":"1.10",
        },
        ".."
      ]
    }
  ]
}

Price calculation

Price calculation is discussed at examples page. There is also some order creation related information at /restaurant/make_order page.

delivery_methods

This field contains delivery methods available for a restaurant. There is more information about how the delivery system should be implemented at /restaurant/delivery_methods.

In this array is zones, that determines delivery range for the delivery method and price for that zone and times that determines the times restaurant has delivery using this delivery method.

delivery method

Each delivery method has delivery_method_id and name. They can also have zones and times arrays.

zones

Zones array defines delivery zones for said delivery method. For example, for area between radius of 5 km and 7 km could be given delivery fee of 14 euros and area betweeen 7 km and 10 km could be given delivery fee of 41,9 euros.

For example, if start_radius is 5 and end_radius is 10, the zone starts from area from 5 kilometers away from restaurant and ends to 10 kilometers from area.

times

Time conditions are used to check if said delivery method matches. It can also be used to check if there should be additional price for delivery fee for certain time frame (nightly increase in delivery fee, for example).

Payment methods

While cash on delivery is maybe the most useful payment method when doing orders with obscure devices like mobile phones, alternative payment methods like mobile phone payment are often useful for customers. These payment methods requires some support from the client, to initiate the payment process and retrieve the data of successful payment.

Payments are made after customer has made an order where she has chosen suitable payment method for the order.

For example, if customer chose a payment method with name “Osuuspankki” (id 64), the server would return order id and url to page where customer can initiate the payment. The client needs to open this URL in a browser, either embedded or external, whichever suits client’s needs best.

In that browser customer can complete the payment, for example by dialing to an order payment number (mobile payments) or do traditional netbank login and payment exactly like it works with computers.

After this customer is returned to the server’s success page (or failure/cancel if there was failure/cancel) where from the client could do some DOM inspection, for example, for page contents in the page to see if order was complete. Then, the client knows the order has been successfully paid and can close the browser and show needed information to the customer.

Few payment methods require extra handling. Those are described at /restaurant/make_order page.

Example list of payment methods

NameValue
"cash"1
"voucher"4
"bonus"8
"po_credit"16
"luottokunta"32
"osuuspankki"64
"nordea"128
"sampopankki"256
"spankki"512
"aktia"1024
"alandsbanken"2048
"tapiola"4096
"handelsbanken"8192
"uphill"32768
"klarna"65536
"poppankki"131072
"saastopankki"262144
"solinor"524288
"danske_mobilepay"1048576
"omasp"2097152

Note: The list below is just for illustrative purposes, real list of methods and bits can be fetched with this action.

Note: bonus, po_credit and voucher are not present in payment_methods array. Those are only used for telling that customer has paid portion or all of order with bonus/voucher/po credit.

Bonus and PO-credit

bonus and po_credit are private cash of user and found from user’s data. When customer wants to use bonus or PO-credit in order, payment method bit needs to be combined with bitwise OR: cash | bonus == 9. This number is then sent to the server which can identify the payment methods customer has used and validate input accordingly.

There is more information of actual attributes at /restaurant/make_order page.

Synopsis

  1. Customer creates an order with payment method that requires payment in advance
  2. Server accepts the order and returns a link to payment method
  3. Client starts a browser and opens the link in it
  4. Customer pays the order in service provider’s system
  5. After successful payment, customer is shown a verification page
  6. Client recognizes customer has been thrown to verification page, validates its contents, closes the browser and shows order data and information about its success.

Return values from payment service provider’s systems are following:

A sole string as content in returned from payment service. "failure" and "cancel" are used somewhat interchangeably; some services does use only one of those states so failure might be returned to cancel url and vice versa.

regular_cash_enabled

If there is regular_cash_enabled set, only people who has already made successfully a prepaid order beforehand can make order with cash payment, no-one else.

To know if user has already made orders to certain restaurant, user’s order history can be fetched with /customer/order_history. If the action returns orders in response, customer has made orders in the service before and so can create cash orders to this restaurant. Please note that orders which has payment method cash does not count.

Expectable errors

See error conventions section for explanation how error system works.

Label Additional data Description
NO_RESTAURANT_IDNoneTried to get restaurant’s data without restaurant id. That won’t do.
INVALID_RESTAURANT_IDNoneThen try to supply real id.