Struct Annotation 

#[non_exhaustive]
pub struct Annotation {
    pub start_index: usize,
    pub end_index: usize,
    pub source: Option<String>,
}

An annotation linking a text span to its source.

Annotations provide citation information for specific portions of generated text, typically appearing when using grounding tools like GoogleSearch or UrlContext.

Byte Indices

Important: The start_index and end_index fields are byte positions (not character indices) in the text content. This matches the UTF-8 byte offsets used by the Gemini API. For multi-byte characters (like emoji or non-ASCII text), you may need to use byte-slicing rather than character indexing.

Example

// Get all annotations from the response
for annotation in response.all_annotations() {
    println!(
        "Text at bytes {}..{} sourced from: {}",
        annotation.start_index,
        annotation.end_index,
        annotation.source.as_deref().unwrap_or("<no source>")
    );
}

Extracting Annotated Text

To extract the annotated substring from the response text:

if let Some(text) = response.as_text() {
    // Use byte slicing since indices are byte positions
    let bytes = text.as_bytes();
    if annotation.end_index <= bytes.len() {
        if let Ok(span) = std::str::from_utf8(&bytes[annotation.start_index..annotation.end_index]) {
            println!("Cited text: {}", span);
        }
    }
}

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

start_index: usize

Start of the segment in the text (byte position, inclusive).

This is a byte offset into the UTF-8 encoded text, not a character index.

end_index: usize

End of the segment in the text (byte position, exclusive).

This is a byte offset into the UTF-8 encoded text, not a character index.

source: Option<String>

Source attributed for this portion of the text.

This could be a URL, title, or other identifier depending on the grounding tool used (e.g., GoogleSearch or UrlContext).

Implementations

impl Annotation

pub fn new(start_index: usize, end_index: usize, source: Option<String>) -> Self

Creates a new annotation with the given span indices and optional source.

Arguments

• start_index - Start of the segment in the text (byte position, inclusive)
• end_index - End of the segment in the text (byte position, exclusive)
• source - Optional source attribution (URL, title, or identifier)

Example

let annotation = Annotation::new(0, 10, Some("https://example.com".to_string()));
assert_eq!(annotation.start_index, 0);
assert_eq!(annotation.end_index, 10);
assert!(annotation.has_source());

pub fn byte_len(&self) -> usize

Returns the byte length of the annotated span.

This is equivalent to end_index - start_index.

pub fn has_source(&self) -> bool

Returns true if this annotation has a source attribution.

pub fn extract_span<'a>(&self, text: &'a str) -> Option<&'a str>

Extracts the annotated substring from the given text.

Returns None if the indices are out of bounds or if the byte slice doesn’t form valid UTF-8.

Arguments

• text - The full text content to extract from

Example

let annotation = Annotation::new(0, 5, Some("https://example.com".to_string()));

let text = "Hello, world!";
assert_eq!(annotation.extract_span(text), Some("Hello"));

Trait Implementations

impl Clone for Annotation

fn clone(&self) -> Annotation

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Annotation

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Annotation

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for Annotation

fn eq(&self, other: &Annotation) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for Annotation

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Eq for Annotation

impl StructuralPartialEq for Annotation