Getting a business

Getting a business

Contents

• Overview
• Version-specific information
• Permissions and Authentication
• Headers
• HTTP Parameters
• Example response JSON

Overview

• Call name: get-business
• Endpoint URL: https://{API hostname}/internal/get-business
• 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 the details of a business.

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
business_id	(integer, mandatory) The ID of the business to fetch

Response Format Notes:

• All coordinates in responses are returned in decimal degrees format:
  • Latitude: decimal value between -90 and +90 degrees
  • Longitude: decimal value between -180 and +180 degrees
• Postal code formats are validated by country:
  • Netherlands (NL): "1234 AB" format (4 digits followed by 2 letters)
  • Belgium (BE): "1234" or "1234 BE" format (4 digits, optionally followed by "BE")
  • Germany (DE): "12345" or "D-12345" format (5 digits, optionally prefixed with "D-")
• String field length constraints:
  • Business name: maximum 255 characters
  • Email address: maximum 255 characters
  • Description: maximum 512 characters
  • Postal code: maximum 20 characters
  • Country code: 2 characters (ISO ALPHA-2 format)
  • Address fields (1,2,3): maximum 255 characters each
  • Town/City: maximum 255 characters
  • Region: maximum 255 characters
  • Phone number: maximum 32 characters
  • Website URL: maximum 255 characters
  • Review URL: maximum 512 characters
  • Image URL: maximum 512 characters
  • Format: maximum 64 characters
  • Owner code: maximum 64 characters
  • Google Place ID: maximum 1024 characters
• Opening times format:

  {
    "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": "12:00", "close": "17:00" },
    "special_hours": [
      {
        "date": "2024-02-23",
        "open": "12:00",
        "close": "17:00",
        "reason": "Laatste zondag van de maand"
      }
    ]
  }

• Boolean fields:
  • programme_opted_in: whether the business participates in the programme
  • is_shut_down: whether the business has been shut down
  • deleted: whether the business has been marked as deleted

Possible error responses

Code	Name	Description	HTTP Status
3	http_vars_missing	Required parameter business_id is missing	400
6	no_valid_session	No valid session key provided or session has expired	401
13	http_request_method_non_GET_not_allowed	Only HTTP GET allowed for this API call	405
15	business_id_invalid	The business_id passed must be an integer	400
68	permission_denied_or_non_existent	User has insufficient permissions or the referenced business does not exist	403
144	business_id_not_found	No record has been found for that business_id	404
441	parameter_missing	A required parameter is missing	400

Example response JSON

The endpoint returns JSON showing the details associated with the business. An example response is shown below:

{
    "result": {
        "code": 1,
        "status": "ok"
    },
    "results": {
        "business": {
            "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"
        },
        "result_type": "get-business"
    }
}