Link Search Menu Expand Document

Getting all businesses

Contents

Overview

  • Call name: get-businesses
  • Endpoint URL: https://api0.spaaza.com/internal/get-businesses
  • Request methods: GET
  • Response Content-Type: application/json
  • Auth required: yes

In Spaaza terminology, a “business” is a branch of a retailer (a “chain”). This API call gets an array of businesses and allows the use of various filters to refine results.

Version-specific information

The following version-specific changes apply to this endpoint. See the versioning page for more details.

Version Change details
N/A N/A

Permissions and Authentication

This API call requires a valid Spaaza session. See the authentication page for more details. The session can be as follows:

  • Admin authentication: The performing user needs to be logged in and have read access to the chain to which the user is connected.

Headers

The following headers can/must be passed to the API call:

Parameter Description
N/A N/A

HTTP Parameters

The following HTTP parameters can be passed to the API:

Parameter Description
chain_id (integer, mandatory) The ID of the chain for which the information is being requested.
name (string, optional, max 255 chars) Comma separated list of business names to filter by. The name is matched as a substring, so passing “foo” will match “foo”, “foobar”, “foo bar”, etc.
owner_code (string, optional, max 64 chars) Comma separated list of owner codes to filter by. The owner code is matched as a substring, so passing “foo” will match “foo”, “foobar”, “foo bar”, etc.
match_all (boolean, optional) Specify true to require that all provided search terms must be present, otherwise if any of the search terms are found the business will be a match.
search_lat and search_long (float optional, both required if used) Search for businesses closest to a latitude and longitude, in decimal degrees (using WGS-84 datum which is default on most GPS and mobile devices). Setting these parameters will result in the distance of the business in kilometres away from the search lat/long. When search_lat and search_long parameters are present, the results are automatically returned in order of distance, closest first.
radius (float optional, only used if search_lat and search_long used as above) Restrict the results to inventory items within a radius of a certain number of kilometres. A default of 25 km is used if search_lat and search_long are set but this value is not set.
exclude_inactive (bool, optional) By default, inactive businesses are included in the results of this endpoint. Inactive businesses are ones where the is_shut_down field is set to true. Setting this flag to true excludes any currently inactive businesses from the results.
limit (integer, optional) Limit the number of results returned. If not set, 500 results are returned.
offset (integer, optional) Offset the results returned. If not set, the results start from the beginning.

Location-based filtering using search_lat and search_long is only be applied if no name or owner_code filtering is specified. Location-based filtering does not support the limit and offset options, instead always returning the first 50 results.

Currently, you can only search for name or owner_code. If both fields are present, the results will be filtered by name only.

Example response JSON

The endpoint returns JSON with an array of businesses, each object showing the details associated with the business. An example response is shown below:

{
    "result": {
        "code": 1,
        "status": "ok"
    },
    "results": {
        "businesses": [
            {
                "address_1": "Herengracht 504",
                "address_2": null,
                "address_3": null,
                "business_format": "Metro",
                "chain_id": 1743,
                "created_date": "2024-04-03T12:43:54+00:00",
                "countrycode": "NL",
                "deleted": false,
                "deleted_by": null,
                "email_address": "ops@spaaza.com",
                "format": "Metro",
                "google_place_id": "ChIJMaAAt6KjMRkRwxomyCkN71w",
                "id": 1383,
                "image_url": "https://media.licdn.com/dms/image/C4D0BAQEN6wx-nP_Crg/company-logo_400_400/0?e=1578528000&v=beta&t=1qKTWg0qbIJMydHHG02YPhD8N4LONyW5Rp06wn5DvN0",
                "is_shut_down": false,
                "last_modified_date": "2024-04-03T12:43:54+00:00",
                "latitude": 52.37021570,
                "longitude": 1.89516789,
                "name": "ACME Inc",
                "opening_times": "{\"monday\": {\"open\": \"11:00\",\"close\": \"18:00\" }, \"tuesday\": { \"open\": \"09:30\", \"close\": \"18:00\" }, \"wednesday\": { \"open\": \"09:30\", \"close\": \"18:00\" }, \"thursday\": { \"open\": \"09:30\", \"close\": \"18:00\" }, \"friday\": { \"open\": \"09:30\", \"close\": \"21:00\" }, \"saturday\": { \"open\": \"09:30\", \"close\": \"17:00\" }, \"sunday\": { \"open\": \"Elke laatste zondag van de maand\", \"close\": \"12:00-17:00\" }, \"special_hours\": [ { \"date\": \"23\/02\/2020\", \"open\": \"12:00\", \"close\": \"17:00\", \"reason\": \"Laatste zondag van de maand\" }, { \"date\": \"23\/02\/2020\", \"open\": \"-\", \"close\": \"-\", \"reason\": \"Carnaval\" } ] }",
                "owner_code": "10001",
                "phone_number": "0124141",
                "postalcode": "1017 CB",
                "programme_opted_in": true,
                "region": "Noord Holland",
                "towncity": "Amsterdam",
                "review_url": "https://g.page/spaaza/review",
                "type": "business",
                "website_url": "https://www.spaaza.com"
            },
            {
                "address_1": "Prinsengracht 263-267",
                "address_2": null,
                "address_3": null,
                "business_format": null,
                "chain_id": 1820,
                "created_date": "2024-03-28T09:15:00+00:00",
                "countrycode": "NL",
                "deleted": false,
                "deleted_by": null,
                "email_address": "contact@vangogh.com",
                "format": "Gallery",
                "google_place_id": "ChIJJ1hK3nIJxkcRjMn3-AQaRzs",
                "id": 1452,
                "image_url": "https://media.vangoghmuseum.nl/dms/image/C4D0BAQG82wx-nP_Crg/museum-logo_400_400/0?e=1609459200&v=beta&t=4rKTWg3qbIJMydHHG02YPhD8N4LONyW5Rp06wn5DvN0",
                "is_shut_down": false,
                "last_modified_date": "2024-03-28T09:15:00+00:00",
                "latitude": 52.35841670,
                "longitude": 4.88109789,
                "name": "Van Gogh Museum",
                "opening_times": "{\"monday\": {\"open\": \"10:00\",\"close\": \"18:00\" }, \"tuesday\": { \"open\": \"09:00\", \"close\": \"18:00\" }, \"wednesday\": { \"open\": \"09:00\", \"close\": \"18:00\" }, \"thursday\": { \"open\": \"09:00\", \"close\": \"21:00\" }, \"friday\": { \"open\": \"09:00\", \"close\": \"18:00\" }, \"saturday\": { \"open\": \"09:00\", \"close\": \"18:00\" }, \"sunday\": { \"open\": \"09:00\", \"close\": \"18:00\" } }",
                "owner_code": "20002",
                "phone_number": "0201234567",
                "postalcode": "1071 XX",
                "programme_opted_in": true,
                "region": "Noord Holland",
                "towncity": "Amsterdam",
                "review_url": "https://g.page/vangoghmuseum/review",
                "type": "museum",
                "website_url": "https://www.vangoghmuseum.nl"
            }
        ],
        "result_type": "get-businesses"
    }
}