Link Search Menu Expand Document

Importing Stores

Contents

Introduction

The Store file describes physical stores in a retail chain including store name, address, retailer-specific store number, and detailed opening hours. This file always includes all stores in the chain including a head office location.

The Store file was previously known as the “Branch file” in earlier versions of the feed specification.

File Structure

The store file contains the following column headings:

"STORE NUMBER","STORE NAME","STORE ADDRESS 1","STORE ADDRESS 2","STORE ADDRESS 3",
"STORE POSTALCODE","STORE COUNTRYCODE","LATITUDE","LONGITUDE","GOOGLE PLACE ID",
"PHONE NUMBER","TOWNCITY","REGION","SHUTDOWN","FORMAT","OPENING HOURS"

Example row:

"ACME_1027","ACME Retailer Anytown","Mall Unit #14","Anytown Mall",
"347 Ancient Heroes Avenue","1000CA","NL","54.24677","4.25666",
"ChIJFVeMnoQJxkcRh95gA0gNHuc","+31 20 555 1234","Anytown","North Anyregion",
0,"Superstore","{\"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\":\"Every last Sunday of the month\",
\"close\":\"12:00-17:00\"},\"special_hours\":[{\"date\":\"23/02/2026\",
\"open\":\"12:00\",\"close\":\"17:00\",\"reason\":\"Laatste zondag van de maand\"},
{\"date\":\"24/02/2026\",\"open\":\"-\",\"close\":\"-\",\"reason\":\"Carnival Time\"}]}"

Sample Store File Data

STORE NUMBER STORE NAME STORE ADDRESS 1 STORE ADDRESS 2 STORE ADDRESS 3 STORE POSTALCODE STORE COUNTRYCODE LATITUDE LONGITUDE GOOGLE PLACE ID PHONE NUMBER TOWNCITY REGION SHUTDOWN FORMAT OPENING HOURS
ACME_1027 ACME Retailer Anytown Mall unit 14 Anytown Shopping Centre 14 Anystreet 1000 ZX NL 54.27401 4.90451 ChIJFVeMnoQJxkcRh95gA0gNHuc +554013274985 Anytown Northern Anyregion 0 Superstore (See JSON example below)
ACME_1093 ACME Retailer Anyville     29 Anyboulevard 2000 AC NL -33.95067 18.376778 ChIJuUZtdVNmzB0R-7OvUK-IBzE +31332915555 Anyville Southern Anyregion 0 Express (See JSON example below)

Download sample store file

Field Definitions

Field Name Description
STORE NUMBER A unique store code used by the retailer to identify the store. The same store code is also used in the Variant List file to identify the store in which a variant is sold. Whilst most stores are recorded with a number, this field has a string value as retailers occasionally use a string value such as “ANYTOWN_001”
STORE NAME The name of the store
STORE ADDRESS 1 The first address field of the store – this is usually used for e.g. the unit location of the store in a shopping mall and maps to the “business_address_1” field in Spaaza API responses
STORE ADDRESS 2 The second address field of the store – this is usually used for e.g. the name of a shopping mall or centre, should that be required, and maps to the “business_address_2” field in Spaaza API responses
STORE ADDRESS 3 The region in which the store is located – this maps to the “business_address_3” field in Spaaza API responses
STORE POSTALCODE The postalcode of the store address
STORE COUNTRYCODE The ISO-3166-1 alpha 2-letter code for the store country, e.g. “NL”
LATITUDE The WGS-84 latitude of the store in decimal degrees, e.g. “54.267755”
LONGITUDE The WGS-84 longitude of the store in decimal degrees, e.g. “4.31723”
GOOGLE PLACE ID The Google Place ID of the store, e.g. “ChIJFVeMnoQJxkcRh95gA0gNHuc”
PHONE NUMBER The phone number of the store. This is accepted in string format to allow for symbols commonly found in phone numbers such as “+”, “(“ or “)”
TOWNCITY The town in which the store is located – this maps to the “business_towncity” field in Spaaza API responses
REGION The postal region in which the store is located – this maps to the “business_address_3” field in Spaaza API responses
SHUTDOWN A Boolean value (0=false, 1=true) denoting whether a store has been administratively closed or not. The default value is 0=false if this field is not included. When this field is set to 1 the store will not be set to deleted in the Spaaza database and analytics will continue to be generated, but the “STORE NUMBER” field can now be used by another store
FORMAT Store format designation, e.g. “Superstore”, “Express”, “Convenience”
OPENING HOURS JSON-encoded opening hours including regular weekly hours and special hours. See Opening Hours JSON Format below for detailed structure

Opening Hours JSON Format

The OPENING HOURS field contains a JSON object with the following structure:

Structure:

{
  "monday": {"open": "HH:MM", "close": "HH:MM"},
  "tuesday": {"open": "HH:MM", "close": "HH:MM"},
  "wednesday": {"open": "HH:MM", "close": "HH:MM"},
  "thursday": {"open": "HH:MM", "close": "HH:MM"},
  "friday": {"open": "HH:MM", "close": "HH:MM"},
  "saturday": {"open": "HH:MM", "close": "HH:MM"},
  "sunday": {"open": "HH:MM or description", "close": "HH:MM or time range"},
  "special_hours": [
    {
      "date": "DD/MM/YYYY",
      "open": "HH:MM or -",
      "close": "HH:MM or -",
      "reason": "Description"
    }
  ]
}

Example 1: Superstore with special hours

{
  "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": "Every last Sunday of the month", "close": "12:00-17:00"},
  "special_hours": [
    {
      "date": "23/02/2026",
      "open": "12:00",
      "close": "17:00",
      "reason": "Laatste zondag van de maand"
    },
    {
      "date": "24/02/2026",
      "open": "-",
      "close": "-",
      "reason": "Carnival Time"
    }
  ]
}

Example 2: Express store with limited hours

{
  "monday": {"open": "08:00", "close": "18:00"},
  "friday": {"open": "08:00", "close": "23:00"}
}
  • Days not specified in the JSON are assumed to be closed
  • For special hours where the store is closed, use “-“ for both open and close times
  • The special_hours array is optional and can contain multiple entries
  • Dates in special_hours use DD/MM/YYYY format
  • Regular opening hours use 24-hour HH:MM format
  • The sunday field can contain descriptive text (e.g. “Every last Sunday of the month”) instead of specific hours