/ 
Net-Async-WebSearch-0.002
/ Net::Async::WebSearch::Result

NAME

Net::Async::WebSearch::Result - Single web search result record

VERSION

version 0.002

SYNOPSIS

my $r = Net::Async::WebSearch::Result->new(
  url      => 'https://example.com/page',
  title    => 'Example Page',
  snippet  => 'Some descriptive snippet...',
  provider => 'duckduckgo',
  rank     => 3,
);

DESCRIPTION

Plain value object produced by a Net::Async::WebSearch::Provider. Carries the per-provider rank position; the aggregate score is filled in later by Net::Async::WebSearch when the collect mode merges results from several providers.

NORMALIZED FIELDS

Every provider promises these fields (though some may be undef when the upstream doesn't supply them):

  • url — result URL (always present, used as the dedup key).

  • title — result title.

  • snippet — short description / passage.

  • provider — name of the emitting provider.

  • rank — 1-indexed position within the emitting provider.

  • domain — derived automatically from the URL via URI, unless the provider overrides it. Convenient for grouping/filtering.

  • score — aggregate RRF score (only set by collect mode).

Optional normalized fields, populated when the provider has the data:

  • published_at — ISO 8601 string (or a human-readable age like "3 days ago" if the provider only gives that).

  • language — BCP-47 language hint (en, de, ...).

  • nsfw — 1 if the upstream flags this result as adult content.

Provider-specific extras (subreddit, sitelinks, MIME type, engine name, ...) live in $r->extra as a hashref. Raw upstream payload, when retained, lives in $r->raw.

url

Result URL. Used as the dedup key (after normalization).

title

Result title as supplied by the provider.

snippet

Short description / snippet for the result.

provider

Name of the provider that emitted this result.

rank

1-indexed position within the emitting provider's result list.

score

Aggregate score (filled in by RRF in collect mode). Read/write.

published_at

Publication timestamp (ISO 8601 or upstream-native string), if the provider surfaces one.

language

BCP-47 language code, if the provider surfaces one.

nsfw

Boolean flag for adult content, if the provider surfaces one.

domain

The hostname parsed out of url (auto-derived if not supplied).

fetched

Populated only when "search" in Net::Async::WebSearch was called with fetch. A hashref describing the HTTP fetch of this result's URL:

{
  ok           => 1,                        # bool
  status       => 200,                      # HTTP code (undef on transport error)
  status_line  => '200 OK',
  final_url    => 'https://example.com/...', # after redirects
  content_type => 'text/html; charset=utf-8',
  charset      => 'utf-8',
  body         => '<html>...</html>',
  error        => undef,                    # error string on failure
}

raw

Optional raw provider payload fragment.

extra

Hashref of provider-specific fields that don't fit the normalized schema (e.g. subreddit, sitelinks, display link, MIME type, engine name).

to_hash

Plain hash representation suitable for JSON serialization (MCP, logs).

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/p5-net-async-websearch/issues.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <torsten@raudssus.de> https://raudss.us/

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.