Easy Calendar - Google Calendar Integration

Parent Category: Documentation Easy Calendar Documentation Last Updated: 21 May 2026 Hits: 101

Connect any EasyCalendar calendar to a Google Calendar and let your availability colour itself in automatically. EasyCalendar reads the events from Google, works out how busy each day is, and paints every day with the legend colour you choose — no manual day-clicking required.

One-way & read-only. Sync flows from Google into EasyCalendar only. EasyCalendar never writes to, edits, or deletes anything in your Google Calendar — it just reads events to decide each day's colour.

How it works

Behind the scenes, EasyCalendar turns Google events into coloured days in four steps:

Fetch & cache — On a schedule (or when you click Sync now), EasyCalendar pulls the upcoming events from your Google Calendar and stores a local copy.
Split the day into time blocks — Each day is divided into 1, 2 or 3 time blocks (e.g. morning / afternoon / evening).
Decide free or booked per block — A block is booked if any event overlaps it, otherwise it's free. This produces a booking pattern for the day.
Colour the day — That pattern is looked up in your legend mapping, and the day is shown in the matching legend's colour.

Display always reads the local copy. Visitors viewing the calendar never wait on Google — they see the last cached sync. How fresh it is depends on how often you sync (see Keeping it in sync below).

Part 1 — Set up Google (one-time)

EasyCalendar authenticates to Google with a service account — a robot account that reads your calendar. You create it once in the free Google Cloud Console, then share your calendar with it.

Go to the Google Cloud Console (console.cloud.google.com) and create a project (or pick an existing one).
Open APIs & Services → Library, search for Google Calendar API, and click Enable.
Open APIs & Services → Credentials → Create credentials → Service account. Give it a name and create it.
Open the new service account → Keys tab → Add key → Create new key → JSON. A .json file downloads — keep it safe, you'll upload it in Part 2.
Copy the service account's email address. It looks like This email address is being protected from spambots. You need JavaScript enabled to view it..
In Google Calendar, open the calendar you want to sync → Settings → Share with specific people → add that service account email with the permission “See all event details”.
Still in the calendar's settings, scroll to Integrate calendar and copy the Calendar ID (e.g. This email address is being protected from spambots. You need JavaScript enabled to view it.).

If you skip the sharing step (step 6), the sync will fail with a “not found / no access” error — even though the key is valid. The service account can only read calendars that have been explicitly shared with its email.

Part 2 — Configure the calendar in EasyCalendar

In Joomla admin, go to Components → Easy Calendar → Calendars, open the calendar you want to sync, and switch to the Google tab. Fill it in top to bottom:

Field	What to enter
Enable Google Calendar sync	Set to Yes. The rest of the fields appear, and starter legends are created automatically the first time.
Google Calendar ID	Paste the Calendar ID from Part 1, step 7.
Service account key (JSON)	Upload the `.json` key from Part 1, step 4. It's stored securely in the database — never written to a file on the server.
Calendar timezone	The timezone used to compare event times against your block split times. Leave blank to use the Joomla site timezone.
Time blocks per day	1, 2 or 3. See Part 3.
Block 1 / Block 2 ends at	The cut-off times between blocks (HH:MM). See Part 3.
Legend mapping	Choose which legend colour shows for each booking pattern. See Part 4.
Fallback legend	Safety-net colour. See Part 5.

Use the “Test integration” button. After entering the Calendar ID and uploading the key, click Test integration. EasyCalendar connects live to Google and reports the calendar's name, its timezone, and how many events it found in the next 30 days — confirming everything works before you rely on it.

Save once before mapping. The Legend mapping table needs the calendar to exist first. If it shows “Save the calendar first”, just save with sync enabled, then return to the Google tab.

Part 3 — Time blocks explained

A time block is a slice of the day that's judged free or booked on its own. Time blocks per day decides how many slices there are, and Block N ends at sets where they split.

Example with 3 blocks, ending at 15:00 and 17:00:

Block	Time range	Typical meaning
Block 1	00:00 → 15:00	Morning / daytime
Block 2	15:00 → 17:00	Late afternoon
Block 3	17:00 → 24:00	Evening

With 2 blocks you'd set a single split (e.g. 12:00) for a simple morning / afternoon (AM / PM) divide. With 1 block the whole day is judged as one unit — booked if there's any event, otherwise free. (“Block 2 ends at” only appears when you pick 3 blocks.)

Changed the block count? Save the calendar. The mapping table redraws from the saved block count, so after changing “Time blocks per day” you must save before the new rows appear.

Part 4 — Legend mapping explained

Once a day is split into blocks, each block is free or booked. That combination is the day's booking pattern, and the Legend mapping table lets you choose a legend colour for every possible pattern.

A block counts as booked if any event overlaps any part of it — an event doesn't have to fill the whole block. When several events fall on the same day, every block they touch is marked booked, then combined into one pattern.

Simple example — 2 blocks (split at 12:00)

Block 1 = morning (00:00–12:00), Block 2 = afternoon/evening (12:00–24:00):

Block 1	Block 2	Day is shown as
free	free	Free
free	booked	Booked PM
booked	free	Booked AM
booked	booked	Fully Booked

Worked example — two ordinary events on one day

Using the 3-block setup above (splits at 15:00 and 17:00), suppose a day in Google has two normal timed events: 10:00–12:00 and 15:00–16:00.

Block	Range	10:00–12:00?	15:00–16:00?	Result
Block 1	00:00–15:00	✓ overlaps	—	booked
Block 2	15:00–17:00	—	✓ overlaps	booked
Block 3	17:00–24:00	—	—	free

The pattern is booked / booked / free, so the day takes whatever legend you mapped to that row. Two short, separate appointments were enough to light up two different blocks — each event simply marks the block(s) it touches, and the results are merged.

Reading the pattern columns. The mapping table has one column per block (left = earliest block of the day) plus a Legend dropdown. With 2 blocks there are 4 rows; with 3 blocks there are 8. Defaults are auto-filled the first time you enable sync, so you only adjust what you want.

Part 5 — Fallback legend

The Fallback legend is the safety net. It's used when:

a booking pattern hasn't been given a legend in the mapping table, or
a legend you mapped earlier was later deleted.

This guarantees every day always has a sensible colour, even if the mapping is incomplete. (If even the fallback is missing, EasyCalendar uses the calendar's first published legend.)

Part 6 — Keeping it in sync

EasyCalendar shows the last cached events, so you decide how often that cache refreshes. There are two ways:

A) Manual — “Sync now”

Go to Components → Easy Calendar → Calendars, tick one or more calendars, and click Sync now in the toolbar. Great for a first run or an immediate refresh. Each calendar's Last synced time (and any Last sync error) is shown in the list.

B) Automatic — Scheduled Task (recommended)

For hands-off, regular updates, use Joomla's built-in scheduler:

Make sure the plugin “EasyCalendar - Google Calendar Sync” is enabled under System → Manage → Plugins.
Go to System → Manage → Scheduled Tasks → New and choose “EasyCalendar: Sync Google Calendar events”.
Set the run interval (e.g. every 15–60 minutes) and save. There are no per-task settings — it uses each calendar's own Google config.
Confirm Joomla's scheduler itself is running (web-cron, a real cron job, or “lazy” on-pageload triggering).

The task refreshes every published calendar that has Google sync enabled.

Global options

Under Components → Easy Calendar → Options → Google Sync:

Sync window (days) — how far ahead events are fetched and cached (default 90, up to 730). Larger windows colour further into the future but pull more data per sync.
Token cache lifetime — how long the Google access token is reused before re-authenticating (default ~55 minutes). Most sites can leave this as-is.

Good to know & behaviour

Manual editing is disabled while sync is on. A synced calendar is driven entirely by Google, so day-clicking/quick-edit is turned off for it. Turn sync off to edit manually again.
All-day & multi-day events mark every block booked for each day they cover — the “fully booked” pattern.
Block boundaries are clean. An event ending exactly at a split time stays in the earlier block; one starting exactly at the split belongs to the later block — no double-counting.
An event crossing a split marks both blocks. e.g. 14:00–16:00 with a 15:00 split marks Block 1 and Block 2.
Time of day matters, not just the date. 3:00–4:00 PM and 3:00–4:00 AM land in different blocks and can produce different colours.
Deleting a legend that's mapped clears those references automatically; the fallback covers affected days until you remap.

Troubleshooting

Symptom	Likely cause & fix
Test says the key is invalid	The JSON must be a genuine Google service account key containing `client_email`, `private_key` and a Google `token_uri`. Re-download it from Google Cloud (Part 1, step 4).
Test connects but finds 0 events / “not found”	The calendar isn't shared with the service account email, or the Calendar ID is wrong. Recheck Part 1, steps 6–7.
Days aren't colouring as expected	Check the Calendar timezone matches how you think about the times, and review your split times and legend mapping rows.
Mapping table has the wrong number of columns	You changed “Time blocks per day” without saving. Save the calendar to redraw the rows.
Calendar shows stale data	Run Sync now, and set up the Scheduled Task (Part 6B) so it refreshes automatically. Check Last sync error in the Calendars list.

Documentation

Find documentation for our Joomla extensions on this page.