Как устроены диапазоны (A1-нотация)

Диапазон — это адрес ячейки или прямоугольной области в A1-нотации, как в привычных электронных таблицах.

Формы записи

Запись	Что означает
A1	одна ячейка
A1:C10	прямоугольник от A1 до C10
Лист1!A1:C10	тот же диапазон на конкретном листе
'Мой лист'!B2	лист с пробелом или спецсимволами — имя в одинарных кавычках

Открытые диапазоны

Запись	Что означает
A:A	весь столбец A
A:C	столбцы A–C целиком
1:1	вся строка 1
A1:A	от A1 и до конца данных столбца

Сервер разворачивает открытый диапазон по фактическому размеру данных и возвращает в ответе поле range с конкретными границами.

URL-кодирование

Если диапазон в пути содержит имя листа (!) или двоеточие (:), закодируйте его: Лист1!A1:C10 → Лист1%21A1%3AC10.

Что приходит в ответе

Значения — сетка по строкам (majorDimension: ROWS по умолчанию). Каждая ячейка — { v, m, f? }: v — исходное значение, m — как видит пользователь, f — формула (если есть). Пустая ячейка — null. Большие диапазоны разбиваются на страницы (pagination с hasMore и nextOffset).

Чтобы получить сетку по столбцам, добавьте ?majorDimension=COLUMNS — внутренние массивы cells станут столбцами. Пагинация при этом остаётся построчной.

Запись: привязка и ориентация

При записи (PUT .../values/{range}, append, batchUpdate) от диапазона в пути используется только верхняя-левая ячейка — как точка привязки. Какие ячейки реально запишутся, определяет форма матрицы values, а не размер диапазона; «хвост» диапазона игнорируется. Указывать многоячейковый диапазон необязательно — можно передать одну ячейку (A1).

Например, A1:A3 с телом {"values": [[10, 2, 5]]} запишет строку A1:C1 (матрица 1×3 от привязки A1), а не столбец A1:A3.

Чтобы записать столбец, есть два пути:

• передать матрицу столбцом: {"values": [[10],[2],[5]]};
• либо оставить строку и указать ориентацию: {"values": [[10,2,5]], "majorDimension": "COLUMNS"}.

В ответе на запись приходит updatedRange — фактический записанный диапазон с именем листа (например Лист 1!A1:C1), а также updatedRows, updatedColumns, updatedCells. Это удобно, чтобы точно видеть, куда легли данные.

Запись затрагивает только ячейки переданного блока — остальное содержимое листа сохраняется.

примечание

Запись доступна только для таблиц в новом (совместном) формате. Для таблиц, созданных в старом формате, запись через API вернёт 422 (Value writes require a collaborative table); чтение при этом работает.

Форматирование ячеек (объединение, границы, цвета, шрифты и начертание, выравнивание, перенос, числовые форматы, ширина столбцов и высота строк) через API не задаётся — доступны только значения.

Числа, даты, формулы

• v типизировано: числа — JSON-числа (1234.5), логические — true/false, текст — строка. Тип одинаков для всего столбца независимо от того, введено значение вручную или посчитано формулой. m — всегда строка по локали документа (1 234,50).
• Даты: в v — серийный номер (число дней от эпохи, например 46037), в m — готовая отформатированная строка. Конвертируйте serial у себя либо используйте m. У ячейки с датой есть поле t: "d", по нему дату можно отличить от обычного числа: { "v": 46037, "m": "15.01.2026", "t": "d" }. У остальных ячеек поля t нет.
• Формулы пишите английскими именами с ; между аргументами: =SUM(A1;B1).

Как записывать числа

• Передавайте число JSON-числом: {"values": [[1234.5]]}. Оно сохранится как число, будет участвовать в формулах и покажется в числовом формате своей ячейки (например 1 234,50 ₽, если у ячейки денежный формат).
• Строка с точкой — "1234.5" — останется текстом: так же таблица поступает, когда это значение вводят вручную. Строка с запятой — "1234,5" — будет распознана как число.
• При чтении числовая ячейка всегда приходит JSON-числом с точкой, как бы её ни ввели: 1234.5, а не "1234,5".

Полный список методов чтения и записи — в Справочнике API.