En esta página, se explica qué son las etiquetas, cómo se administran en los calendarios y cómo puedes asignarlas a eventos con la API de Calendario de Google.
El Calendario de Google te permite personalizar el aspecto de tus eventos asignándoles nombres y colores personalizados. Anteriormente, los eventos se limitaban a un conjunto fijo de colores basados en índices (colorId). Con las etiquetas, puedes definir una paleta personalizada y flexible por calendario, y aplicar estas etiquetas directamente a los eventos.
Administra etiquetas en un calendario
Puedes definir hasta 200 etiquetas personalizadas por calendario con la labelProperties propiedad en el recurso Calendars.
Para administrar etiquetas, usa los Calendars.insert o Calendars.update métodos. Cada etiqueta requiere un id, un backgroundColor en formato hexadecimal y un name opcional.
Representación del recurso de calendario
{
"kind": "calendar#calendar",
"id": "primary",
"summary": "My Team Calendar",
"labelProperties": {
"eventLabels": [
{
"id": "42617328-8756-4291-8273-192837465647",
"backgroundColor": "#039be5",
"name": "Important Project"
},
{
"id": "19283746-9182-4736-8271-918273645261",
"backgroundColor": "#33b679",
"name": "Team Meeting"
}
]
}
}
Ejemplo: Agrega y quita etiquetas en un calendario
Para agregar o quitar etiquetas, primero debes leer el calendario para obtener la lista actual de etiquetas, modificar la lista en tu código y, luego, actualizar el calendario con la lista actualizada para evitar que se reemplacen otras etiquetas.
En los siguientes ejemplos, se muestra cómo recuperar un calendario, quitar una etiqueta con el ID 11111111-2222-3333-4444-555555555555, agregar dos etiquetas nuevas (22222222-3333-4444-5555-666666666666 y 33333333-4444-5555-6666-777777777777) y actualizar el calendario:
Go
// Refer to the Go quickstart on how to setup the service:
// https://developers.google.com/workspace/calendar/quickstart/go
// 1. Read the calendar to get existing labels
calendar, err := srv.Calendars.Get("primary").Do()
if err != nil {
log.Fatalf("Unable to retrieve calendar: %v", err)
}
if calendar.LabelProperties == nil {
calendar.LabelProperties = &calendar.LabelProperties{}
}
labels := calendar.LabelProperties.EventLabels
// 2. Remove a label with a specific ID (UUID format)
targetIdToRemove := "11111111-2222-3333-4444-555555555555"
var updatedLabels []*calendar.EventLabel
for _, label := range labels {
if label.Id != targetIdToRemove {
updatedLabels = append(updatedLabels, label)
}
}
labels = updatedLabels
// 3. Add 2 new labels with UUID IDs
labels = append(labels, &calendar.EventLabel{
Id: "22222222-3333-4444-5555-666666666666",
BackgroundColor: "#8e24aa",
Name: "Design Work",
})
labels = append(labels, &calendar.EventLabel{
Id: "33333333-4444-5555-6666-777777777777",
BackgroundColor: "#f4511e",
Name: "Urgent Review",
})
// 4. Update the calendar with the new list
calendar.LabelProperties.EventLabels = labels
updatedCalendar, err := srv.Calendars.Update("primary", calendar).Do()
if err != nil {
log.Fatalf("Unable to update calendar: %v", err)
}
fmt.Printf("Calendar updated: %s\n", updatedCalendar.Summary)
Java
// Refer to the Java quickstart on how to setup the service:
// https://developers.google.com/workspace/calendar/quickstart/java
// 1. Read the calendar to get existing labels
Calendar calendar = service.calendars().get("primary").execute();
LabelProperties labelProperties = calendar.getLabelProperties();
if (labelProperties == null) {
labelProperties = new LabelProperties();
}
List<EventLabel> labels = labelProperties.getEventLabels();
if (labels == null) {
labels = new ArrayList<>();
} else {
// Create a mutable copy since the returned list might be immutable
labels = new ArrayList<>(labels);
}
// 2. Remove a label with a specific ID (UUID format)
String targetIdToRemove = "11111111-2222-3333-4444-555555555555";
labels.removeIf(label -> targetIdToRemove.equals(label.getId()));
// 3. Add 2 new labels with UUID IDs
labels.add(new EventLabel()
.setId("22222222-3333-4444-5555-666666666666")
.setBackgroundColor("#8e24aa")
.setName("Design Work"));
labels.add(new EventLabel()
.setId("33333333-4444-5555-6666-777777777777")
.setBackgroundColor("#f4511e")
.setName("Urgent Review"));
// 4. Update the calendar with the new list
labelProperties.setEventLabels(labels);
calendar.setLabelProperties(labelProperties);
Calendar updatedCalendar = service.calendars().update("primary", calendar)
.execute();
System.out.printf("Calendar updated: %s\n", updatedCalendar.getSummary());
JavaScript
// Refer to the Node.js quickstart on how to setup the service:
// https://developers.google.com/workspace/calendar/quickstart/nodejs
// 1. Retrieve the calendar resource
calendar.calendars.get({
calendarId: 'primary'
}, (err, res) => {
if (err) return console.log('The API returned an error: ' + err);
// Extract existing labels from the calendar resource
const cal = res.data;
if (!cal.labelProperties) {
cal.labelProperties = {};
}
if (!cal.labelProperties.eventLabels) {
cal.labelProperties.eventLabels = [];
}
// 2. Remove a label with a specific ID (UUID format)
const targetIdToRemove = '11111111-2222-3333-4444-555555555555';
cal.labelProperties.eventLabels = cal.labelProperties.eventLabels.filter(
label => label.id !== targetIdToRemove
);
// 3. Add 2 new labels with UUID IDs
cal.labelProperties.eventLabels.push({
id: '22222222-3333-4444-5555-666666666666',
backgroundColor: '#8e24aa',
name: 'Design Work'
});
cal.labelProperties.eventLabels.push({
id: '33333333-4444-5555-6666-777777777777',
backgroundColor: '#f4511e',
name: 'Urgent Review'
});
// 4. Update the calendar with the new list
calendar.calendars.update({
calendarId: 'primary',
resource: cal
}, (updateErr, updateRes) => {
if (updateErr) return console.log('Update failed: ' + updateErr);
console.log(`Calendar updated: ${updateRes.data.summary}`);
});
});
Python
# Refer to the Python quickstart on how to setup the service:
# https://developers.google.com/workspace/calendar/quickstart/python
# 1. Read the calendar to get existing labels
calendar = service.calendars().get(calendarId='primary').execute()
label_properties = calendar.setdefault('labelProperties', {})
labels = label_properties.setdefault('eventLabels', [])
# 2. Remove a label with a specific ID (UUID format)
target_id_to_remove = "11111111-2222-3333-4444-555555555555"
labels = [l for l in labels if l.get('id') != target_id_to_remove]
# 3. Add 2 new labels with UUID IDs
labels.append({
'id': '22222222-3333-4444-5555-666666666666',
'backgroundColor': '#8e24aa',
'name': 'Design Work'
})
labels.append({
'id': '33333333-4444-5555-6666-777777777777',
'backgroundColor': '#f4511e',
'name': 'Urgent Review'
})
# 4. Update the calendar with the new list
label_properties['eventLabels'] = labels
calendar['labelProperties'] = label_properties
updated_calendar = service.calendars().update(
calendarId='primary',
body=calendar
).execute()
print(f"Calendar updated: {updated_calendar.get('summary')}")
HTTP
En el siguiente ejemplo de HTTP sin procesar, se muestra la solicitud PUT final para actualizar el calendario con la nueva lista de etiquetas. Asegúrate de haberlas combinado primero con las etiquetas existentes.
PUT https://www.googleapis.com/calendar/v3/calendars/primary
Authorization: Bearer [YOUR_ACCESS_TOKEN]
Content-Type: application/json
{
"summary": "Updated Team Calendar",
"labelProperties": {
"eventLabels": [
{
"id": "22222222-3333-4444-5555-666666666666",
"backgroundColor": "#8e24aa",
"name": "Design Work"
},
{
"id": "33333333-4444-5555-6666-777777777777",
"backgroundColor": "#f4511e",
"name": "Urgent Review"
}
]
}
}
Asigna etiquetas a eventos
Una vez que se definen las etiquetas en el calendario, puedes asignarlas a eventos individuales configurando la eventLabelId propiedad en el recurso Events.
Puedes establecer o cambiar esta propiedad cuando llamas a los métodos insert, update o patch.
Representación del recurso de evento
{
"kind": "calendar#event",
"id": "sample-event-id",
"summary": "Review Design Specs",
"start": {
"dateTime": "2026-07-01T10:00:00Z"
},
"end": {
"dateTime": "2026-07-01T11:00:00Z"
},
"eventLabelId": "22222222-3333-4444-5555-666666666666"
}
Ejemplo: Crea un evento con una etiqueta
En los siguientes ejemplos, se muestra cómo crear un evento con una etiqueta personalizada:
Go
// Refer to the Go quickstart on how to setup the service:
// https://developers.google.com/workspace/calendar/quickstart/go
event := &calendar.Event{
Summary: "Design Sync",
Start: &calendar.EventDateTime{
DateTime: "2026-07-02T14:00:00Z",
},
End: &calendar.EventDateTime{
DateTime: "2026-07-02T15:00:00Z",
},
EventLabelId: "22222222-3333-4444-5555-666666666666",
}
createdEvent, err := srv.Events.Insert("primary", event).EventLabelVersion(1).Do()
if err != nil {
log.Fatalf("Unable to create event: %v", err)
}
fmt.Printf("Event created: %s\n", createdEvent.HtmlLink)
Java
// Refer to the Java quickstart on how to setup the service:
// https://developers.google.com/workspace/calendar/quickstart/java
Event event = new Event()
.setSummary("Design Sync")
.setStart(new EventDateTime().setDateTime(new DateTime("2026-07-02T14:00:00Z")))
.setEnd(new EventDateTime().setDateTime(new DateTime("2026-07-02T15:00:00Z")))
.setEventLabelId("22222222-3333-4444-5555-666666666666");
Event createdEvent = service.events().insert("primary", event)
.setEventLabelVersion(1L)
.execute();
System.out.printf("Event created: %s\n", createdEvent.getHtmlLink());
JavaScript
// Refer to the Node.js quickstart on how to setup the service:
// https://developers.google.com/workspace/calendar/quickstart/nodejs
const event = {
summary: 'Design Sync',
start: {
dateTime: '2026-07-02T14:00:00Z',
},
end: {
dateTime: '2026-07-02T15:00:00Z',
},
eventLabelId: '22222222-3333-4444-5555-666666666666',
};
calendar.events.insert({
calendarId: 'primary',
resource: event,
eventLabelVersion: 1,
}, (err, res) => {
if (err) return console.log('The API returned an error: ' + err);
console.log(`Event created: ${res.data.htmlLink}`);
});
Python
# Refer to the Python quickstart on how to setup the service:
# https://developers.google.com/workspace/calendar/quickstart/python
event = {
'summary': 'Design Sync',
'start': {
'dateTime': '2026-07-02T14:00:00Z',
},
'end': {
'dateTime': '2026-07-02T15:00:00Z',
},
'eventLabelId': '22222222-3333-4444-5555-666666666666'
}
event = service.events().insert(
calendarId='primary',
body=event,
eventLabelVersion=1
).execute()
print(f"Event created: {event.get('htmlLink')}")
HTTP
POST https://www.googleapis.com/calendar/v3/calendars/primary/events?eventLabelVersion=1
Authorization: Bearer [YOUR_ACCESS_TOKEN]
Content-Type: application/json
{
"summary": "Design Sync",
"start": {
"dateTime": "2026-07-02T14:00:00Z"
},
"end": {
"dateTime": "2026-07-02T15:00:00Z"
},
"eventLabelId": "22222222-3333-4444-5555-666666666666"
}
Para quitar una etiqueta existente de un evento, establece eventLabelId en una cadena vacía ("") o omite el campo por completo en una solicitud update.