Importing Stores

Introduction
File Structure
Sample Store File Data
Field Definitions
Opening Hours JSON Format

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.

note

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"}
}

note

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