--- title: "Allows to get merchant information by parameters" method: GET path: "/v1/merchants" tags: ["merchants"] --- # Allows to get merchant information by parameters `GET /v1/merchants` ###Description This endpoint is used to search merchants by a set of parameters. For each merchant in the result there is information about location, language and tags that describe this merchant's basic characteristics, there is also a set of images selected by the merchant. ####Possible query parameters: ##Mandatory geo parameters (at least one of two options must be provided) * **place**: Filter for merchant on a country, city or district whose name matches the parameter. (if the parameter does not match any city or district on the system it is ignored) * **centerPoint**: Filter merchants within the circle defined by center on centerPoint and radius defined by radius parameter (if not informed defaults to 10). Center point has the format LATITUDE,LONGITUDE with both parameters as numbers with . as decimal separator (e.g `centerPoint=52.547928,13.4085728`) * **query**: Filter merchants using text similarity on a number of merchant fields like name, description, categories and tags * **placeIds**: DEPRECATED. Filter for merchant by id of place. Semicolon separated integer value. * **radius**: The radius of the circle to filter merchants in **kilometers**. Defaults to 10 and is only used if *centerPoint* is also informed * **bookable**: Boolean value, if informed true means that only merchants that are online bookable will be returned and false means that only merchants that are NOT online bookable will be returned * **tags**: Filter out merchants with the selected tags text. Semicolon separated text value. All or nothing field: if a tag is not found, the query will fail. Cannot be used in conjunction with 'tagIds' parameter. * **tagIds**: Filter out merchants with the selected tag ids. Semicolon separated text value. All or nothing field: if a tag is not found, the query will fail. Cannot be used in conjunction with 'tags' parameter. * **reviewScoreMax**: Filter out merchants with review score higher than the one informed. * **onlyWithAttributes**: This field only accepts the value **documents** for now. If informed only merchants with documents will be returned. You need to have required permissions to use this filter * **capacity**: Number of people. In order to be effective, "place", "date" and "fromTime" must also be set. * **date**: Date of the desired reservation in merchants' time zone. Format: yyyy-MM-dd. Availability search is only activated if "place" is specified. * **fromTime**: Beginning of the desired reservation time frame in merchants' time zone. Format: HH:mm. Consider a 3h buffer for the time (0.5h before the given time and 2.5h after) * **offset**: Number of merchants to skip on the result. Defaults to 0 * **limit**: Maximum number of merchants to return. Defaults to 100 and cannot be more than 100. * **ivrNumber**: Filter out merchants with phone number. ####Result fields for Merchant object: * **id**: Id of the merchant * **name**: Name of the merchant * **phoneNumber**: The phone number of the merchant * **currency**: Currency of the merchant in the ISO 4217 letter format * **locale**: Locale used to communicate with this merchant * **timezone**: Canonical Timezone name * **location**: Location of the merchant, contains both an geo located point and an address if available * **reviewScore**: Review score of the merchant * **tagGroups**: Tags (grouped) about relevant merchant characteristics * **images**: Group of images selected by the merchant * **documents**: Group of documents released by this merchant (e.g seasonal menus ) * **links**: Links for other pages or api operations for this merchant * **bookable**: The flag indicates whether the merchant is bookable or not * **openingTimes**: Group of opening times: restaurant opening times for this merchant. Time range beginning may be greater than the end time of the range, when this range goes beyond the day when it was started, e.g. 19:00:00 - 02:00:00 * **ccvEnabled**: If true, credit card information is required when creating a reservation * **chain**: Merchant chain information, if any * **ivrRedirectNumber**: The IVR forwarding phone number, requires permission * **shortDescription**: Merchant short description, requires permission * **longDescription**: Merchant long description, requires permission ###Authenticated use of the api: * Field `documents` is only accessible for authorized callers and will be empty otherwise. * Queries with parameter `onlyWithAttributes` are only allowed for authorized callers and will return `HTTP 403` for unauthorized requests #####How? In order to make an authenticated call the caller must send a header name `X-Quandoo-AuthToken` with the token obtained from contact with Quandoo. ###Pagination of the result: The result contains the fields `size` with the number of all merchants that matched the informed parameters, `offset` and `limit` defining which merchants from the complete list are on this response, and the caller can use query parameters `offset` and `limit` to get different merchants on the result list ###Examples: Example curl: ``` curl -H 'X-Quandoo-AuthToken: INSERT_KEY_HERE' 'https://{host}/v{X}/merchants?query=Zim&place=Berlin&centerPoint=52.5479288%2C13.4085728&radius=10&bookable=true&reviewScoreMax=200&onlyWithAttributes=documents&offset=0&limit=100' ``` Example response: ``` { "merchants": [ { "id": 215, "name": "a-merchant-Zim", "phoneNumber": "+49153153153", "currency": "EUR", "locale": "de_DE", "timezone": "Europe/Berlin", "location": { "coordinates": { "latitude": 55, "longitude": 12 }, "address": {} }, "reviewScore": "5.3", "tagGroups": [ { "type": "CUISINE", "tags": [ { "id": 63, "name": "Testküche Hauptkategorie" }, { "id": 66, "name": "Test cuisine" } ] } ], "images": [], "documents": [ { "name": "Main Menu", "url": "https://d2s6u6f7snurg9.cloudfront.net/partner/uploads/MD-document-3ec1dc15-1b69-463f-bdd2-c060b9bf844d.pdf", "format": "pdf", "description": "Seasonal Main Menu" } ], "links": [ { "href": "https://{host}/{path}?aid=16", "method": "GET", "rel": "DETAILS" }, { "href": "https://{host}/{path}?aid=16&countryId=NLD", "method": "GET", "rel": "WIDGET" }, { "href": "https://{host}/{path}/details?aid=16&countryId=NLD", "method": "GET", "rel": "WIDGET_DETAILS" } ], "bookable": true, "ccvEnabled": true, "chain": { "id": 1, "name": "Test chain" }, "ivrRedirectNumber": "+49153153153", "shortDescription": "Test short description", "longDescription": "Test long description", }, { "id": 219, "name": "another merchants Zim", "phoneNumber": "+49154154154", "currency": "EUR", "locale": "de_DE", "timezone": "Europe/Berlin", "location": { "coordinates": { "latitude": 52, "longitude": 13 }, "address": { "street": "Wintersteinstr.", "number": "15", "zipcode": "10587", "city": "Berlin", "country": "DEU" } }, "reviewScore": "4.7", "tagGroups": [ { "type": "CUISINE", "tags": [ { "id": 79, "name": "Testküche Hauptkategorie" }, { "id": 82, "name": "Test Japanese" } ] }, { "type": "PRICE", "tags": [ { "id": 84, "name": "Test expensive" } ] } ], "images": [ { "url": "https://dci5ez2ey8tr9.cloudfront.net/1482eec7-e585-4821-b096-8a9941e0d2eb/25_sld.jpg" } ], "documents": [], "links": [ { "href": "https://{host}/{path}?aid=16", "method": "GET", "rel": "DETAILS" }, { "href": "https://{host}/{path}?aid=16&countryId=NLD", "method": "GET", "rel": "WIDGET" }, { "href": "https://{host}/{path}/details?aid=16&countryId=NLD", "method": "GET", "rel": "WIDGET_DETAILS" } ], "bookable": true, "openingTimes": { "standardOpeningTimes": { "SATURDAY": [ { "start": "09:00:00", "end": "20:00:00" } ], "SUNDAY": [ { "start": "09:00:00", "end": "18:00:00" } ] } }, "ccvEnabled": true, "chain": { "id": 1, "name": "Test chain" }, "ivrRedirectNumber": "+49153153153", "shortDescription": "Test short description", "longDescription": "Test long description", } ], "size": 2, "offset": 0, "limit": 100 } ``` ## Query parameters - `query` string - `place` string - `placeIds` string - `centerPoint` string - `radius` integer - `bookable` boolean - `tags` string - `tagIds` string - `reviewScoreMax` integer - `onlyWithAttributes` string - `capacity` integer, required - `date` string, date - `fromTime` string - `offset` integer - `limit` integer - `ivrNumber` string ## Headers - `Accept-Language` string ## Response `200` OK - MerchantDetailsDtoList - `merchants` MerchantDetailsDto[], required — Merchant details collection. - `id` integer, required — The id of the merchant. - `name` string, required — The name of the merchant. - `phoneNumber` string, required — The phone number of the merchant. - `currency` string — The currency of the merchant. - `locale` string — The locale of the merchant. - `timezone` string, required — The timezone of the merchant. - `location` LocationDto, required - `coordinates` CoordinatesDto - `latitude` number, double - `longitude` number, double - `address` MerchantAddressDto - `street` string - `number` string - `zipcode` string - `city` string - `country` string - `district` string - `reviewScore` string, required — The review score of the merchant. - `tagGroups` TagGroupDto[] — The tag groups this merchant belongs to, requires permission. Without permissions returns only CUISINE and PRICE. - `type` 'CUISINE' | 'MEAL_TYPE' | 'ESTABLISHMENT_TYPE' | 'AREA' | 'INTERNET' | 'FOOD_RELATED' | 'ACCESSIBILITY' | 'PAYMENT' | 'PRICE' | 'ATMOSPHERE' | 'PARKING' | 'EXTRAS' | 'GOOD_FOR' | 'MENU_DETAILS' - `tags` TranslatedTagDto[] - `id` string, uuid - `name` string - `images` ImageDto[] — The slider images this merchant has. - `url` string, url - `documents` DocumentDto[] — The documents this merchant has, requires permission. - `name` string - `url` string - `format` string - `description` string - `links` LinkRelationDto[], required — The links related to this entity. - `href` string, url - `method` string - `rel` 'DETAILS' | 'WIDGET' | 'WIDGET_DETAILS' | 'GET_MERCHANT' | 'PARENT' | 'SELF' | 'SETTINGS' | 'AVAILABILITY_DAYS' | 'AVAILABILITIES' | 'CREATE_RESERVATION' | 'GET_RESERVATION' | 'UPDATE_RESERVATION' | 'GET_CUSTOMER_RESERVATION' | 'GET_REVIEW' | 'PORTAL_PREORDER_FORM' | 'RESERVATION_CHECKOUT_PAGE' | 'CREDIT_CARD_DETAILS_PAGE' | 'CUSTOMER_EDIT_RESERVATION' - `bookable` boolean, required — The flag indicates whether the merchant is bookable or not. - `openingTimes` OpeningTimesDto, required - `standardOpeningTimes` StandardOpeningTimesDto, required - `ccvEnabled` boolean, required — If true, credit card information is required when creating a reservation. - `chain` ChainDto - `id` integer - `name` string - `ivrRedirectNumber` string — The IVR forwarding phone number, requires permission. - `shortDescription` string — Merchant short description, requires permission. - `longDescription` string — Merchant long description, requires permission. - `size` integer - `offset` integer - `limit` integer ## Other responses - `400` — Bad request --- [API](https://skmtc.net/quandoo/apis/quandooapidocumentation.md) · [All operations](https://skmtc.net/quandoo/apis/quandooapidocumentation/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/quandoo/quandooapidocumentation/revisions/6863a5956792/schema)