Enum Annotation 

#[non_exhaustive]
pub enum Annotation {
    UrlCitation {
        url: Option<String>,
        title: Option<String>,
        start_index: usize,
        end_index: usize,
    },
    FileCitation {
        document_uri: Option<String>,
        file_name: Option<String>,
        source: Option<String>,
        custom_metadata: Option<Value>,
        page_number: Option<u32>,
        media_id: Option<String>,
        start_index: usize,
        end_index: usize,
    },
    PlaceCitation {
        place_id: Option<String>,
        name: Option<String>,
        url: Option<String>,
        review_snippets: Vec<ReviewSnippet>,
        start_index: usize,
        end_index: usize,
    },
    Unknown {
        annotation_type: String,
        data: Value,
    },
}

A citation annotation attached to text content.

Annotations link byte ranges of the text (start_index..end_index, UTF-8 byte offsets) to their sources. Revision 2026-05-20 uses a discriminated union over type: url_citation, file_citation, and place_citation.

Forward Compatibility

#[non_exhaustive]; unrecognized annotation types deserialize into Annotation::Unknown with the full JSON preserved.

Example

let text = response.all_text();
for annotation in response.all_annotations() {
    match annotation {
        Annotation::UrlCitation { url, title, .. } => {
            println!("Source: {:?} ({:?})", title, url);
        }
        Annotation::Unknown { annotation_type, .. } => {
            println!("Unknown annotation type: {}", annotation_type);
        }
        _ => {}
    }
    if let Some(span) = annotation.extract_span(&text) {
        println!("  Cited text: {}", span);
    }
}

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

UrlCitation

A citation of a web source (type: "url_citation").

Fields

url: Option<String>

The cited URL.

title: Option<String>

Title of the cited page.

start_index: usize

Start of the cited span (UTF-8 byte offset, inclusive).

end_index: usize

End of the cited span (UTF-8 byte offset, exclusive).

FileCitation

A citation of an uploaded/retrieved document (type: "file_citation").

Fields

document_uri: Option<String>

URI of the cited document.

file_name: Option<String>

Name of the cited file.

source: Option<String>

Source store or origin of the file.

custom_metadata: Option<Value>

Custom metadata attached to the document.

page_number: Option<u32>

Page number of the citation, if applicable.

media_id: Option<String>

Media identifier within the document.

start_index: usize

Start of the cited span (UTF-8 byte offset, inclusive).

end_index: usize

End of the cited span (UTF-8 byte offset, exclusive).

PlaceCitation

A citation of a Google Maps place (type: "place_citation").

Fields

place_id: Option<String>

Google Maps place identifier.

name: Option<String>

Name of the place.

url: Option<String>

URL of the place.

review_snippets: Vec<ReviewSnippet>

Review snippets supporting the citation.

start_index: usize

Start of the cited span (UTF-8 byte offset, inclusive).

end_index: usize

End of the cited span (UTF-8 byte offset, exclusive).

Unknown

Unknown annotation type for forward compatibility.

Fields

annotation_type: String

The unrecognized type name from the API.

data: Value

The full JSON data, preserved for debugging and roundtrip.

Implementations

impl Annotation

pub fn url_citation( url: impl Into<String>, title: Option<String>, start_index: usize, end_index: usize, ) -> Self

Creates a URL citation annotation.

pub const fn is_unknown(&self) -> bool

Check if this is an unknown annotation type.

pub fn unknown_annotation_type(&self) -> Option<&str>

Returns the annotation type name if this is an unknown annotation.

pub fn unknown_data(&self) -> Option<&Value>

Returns the raw JSON data if this is an unknown annotation.

pub fn start_index(&self) -> Option<usize>

Start of the annotated span (UTF-8 byte offset, inclusive).

Returns None for Annotation::Unknown without a numeric start_index field.

pub fn end_index(&self) -> Option<usize>

End of the annotated span (UTF-8 byte offset, exclusive).

pub fn source(&self) -> Option<&str>

Returns the primary source identifier for this annotation, if any.

• url_citation → the URL
• file_citation → the document URI (or file name)
• place_citation → the place URL (or place ID)

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 missing, out of bounds, or don’t fall on valid UTF-8 boundaries.

Example

let annotation = Annotation::url_citation("https://example.com", None, 0, 5);
assert_eq!(annotation.extract_span("Hello, world!"), Some("Hello"));

Trait Implementations

impl Clone for Annotation

fn clone(&self) -> Self

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: &Self) -> bool

Equality operator ==.

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

Inequality operator !=.

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 StructuralPartialEq for Annotation