In this article we’ll take a look at Base64, what it is and why we use it. Although there are Base64 encoding and decoding available in the Apps Script Utilities service, we’ll write an encoder and (maybe) a decoder as a learning exercise.

What is Base64?

Base64 refers to the radix, or the number of unique characters in an encoding system. You can think of this in terms of other radices that you might be more familiar with in the table below

 Radix Name Character set number of bits one character can exactly represent (power of 2)
 2  binary  0-1 1
 8  octal  0-7 3
 10  decimal  0-9  n/a
 16  hex  0-9,a-f  4
 64  base64  0-9,A-Z,a-z,+,/  6
 256  byte  binary 0-255  8

The purpose of base64 is to represent binary data in some printable form, so it can be sent losslessly over media transports that are only designed to deal with text data. Many Http services, APIs (and email) encode their data to base64 during transmission. There are other encoding systems such as uuencode and Base85, but the most common is Base64.

As per the table above, base64 is only capable of representing 6 bits per character, but binary data could need all 8 bits in a byte. This means that a Base64 string of characters will be longer than the number of bytes in the original. In fact each group of 3 bytes needs 4 base64 characters to represent it.

Encoding base64.

It’s pretty straightforward to convert a byte array (or another string) to Base64. The only tricky bit is where the input number of characters is not exactly divisible by 3, in which case you have to use some padding.

Here’s a simple encoder. It’s written to be able to take either a string or a Byte[] as input.

Decoding Base64

It should be fairly straightforward to reverse engineer this. Your homework is to submit a decoder to me on our forum, and I’ll publish the best one.


Here’s a test comparing the results of this function to the Utilities.base64Encode(). This generates 1000 tests with random Byte Arrays and succeeds.


It’s always going to be better to use the inbuilt Utilities function, but here’s a rare chance to see the difference in performance between something coded in apps script and its native counterpart. – You can see that

is over 7 times as fast as my attempt at an equivalent in apps script.

[15-04-01 14:56:02:979 BST] Time for Utilities.base64Encode(data):963
[15-04-01 14:56:02:980 BST] Time for sampleB64Encode):7494

Although, when you run this as a client app on chrome – the same code runs superfast and the difference is minimal

Here’s the test.

Many of the snippets in this section of the site are part of the cUseful library. You can find the details here.
For more like this see Google Apps Scripts Snippets
Why not join our forum,follow the blog or follow me on twitter to ensure you get updates when they are available.