search api

Search API

• Name: dist
• Returns: application/json
• URI Template Variables: {in}
• Availability: API Server

Full text search API. Returns JSON describing the search results, as well as a few metadata points. The index to be searched is determined by the {in} URI template variable, which may be any one of the following values:

• docs: Search the documentation.
• dists: Search distribution metadata, including READMEs and tags.
• extensions: Search extension metadata
• tags: Search tags
• users: Search users

Parameters

In addition to the JSONP callback parameter supported by all the JSON-returning APIs, the search API supports the following parameters. Each must be submitted via a URL-encoded GET query string ("R" column indicates required parameters):

R	Param	Type	Default	Description
•	q	String		The search query.
	o	Number	0	Query results offset.
	l	Number	50	Query results limit.

The offset may be any positive integer and defaults to 0. The limit may be any positive integer between 1 and 1024. Defaults to 50 when not specified, and reverts to 50 when any non-supported value is passed.

Query Syntax

Search queries are free-form but support a few operators.

• Boolean operators AND, OR, and AND NOT.
• Logical groups, delimited by parentheses.
• Phrases, delimited by double quotes.
• Prepended + (plus) and - (minus) to require or prevent a match against a word, phrase, or parenthetical group.
• Search a single field with fieldname:termtext or fieldname:(foo bar).

Without operators, multiple search terms are ORed together. So a search for "foo bar" is the same as "foo OR bar".

The fields available for targeted searching are specific to the type of index specified by the {in} UIR template variable as follows:

Index	Fields
docs	title, abstract, body, dist, user, user_name
dists	dist, abstract, description, readme, tags, user, user_name
extensions	extension, abstract, user, user_name
users	user, name, details
tags	tag

By default, if no field is specified in the search query, all fields are searched.

Result Structure

The structure of the returned API is a single JSON object with the following keys:

Key	Type	Description
query	String	The search query string
offset	Number	The the results offset.
limit	Number	The results limit.
count	Number	The total number of results.
hits	Array	The actual results in descending order by score.

The contents of the hits array is a list of objects, the structure of which varies depending on the value of the {in} URI template variable. A few examples:

• Search for "test" in "docs"
• Search for "test" in "docs" with offset 1
• Search for "test" in "docs" with limit 1
• Search for "test" in "dists"
• Search for "integer" in "extensions"
• Search for "test" in "tags"
• Search for "david" in "users"
• Search for "user:theory" in "dists"

Docs Hits

Each hit when when searching the docs index reflects a single documentation file from the latest release of a distribution. The hit objects contain the following keys:

Key	Type	Description
title	String	The title of the document
excerpt	String	An excerpt from the document highlighting matched terms in <strong> elements.
abstract	String	A short description of the extension documented, if any.
dist	String	The name of the distribution in which the document is found.
version	SemVer	The version of the distribution release in which the document is found.
docpath	String	The path to the document within the distribution release, sans file name suffix.
date	Date	The date the release was uploaded to PGXN.
user	String	The nickname of the user who uploaded this release of the distribution.
user_name	String	The full name of the user who uploaded this release of the distribution.

Dists Hits

Each hit when when searching the dists index reflects the latest release of a single distribution. The hit objects contain the following keys:

Key	Type	Description
dist	String	The name of the distribution.
version	SemVer	The version of the distribution release.
excerpt	String	An excerpt from the distribution README highlighting matched terms.
abstract	String	A short description of the distribution.
date	Date	The date the release was uploaded to PGXN.
user	String	The nickname of the user who uploaded this release of the distribution.
user_name	String	The full name of the user who uploaded this release of the distribution.

Extensions Hits

Each hit when when searching the extensions index reflects the latest release of a single extension. The hit objects contain the following keys:

Key	Type	Description
extension	String	The name of the extension.
excerpt	String	An excerpt from the extension abstract highlighting matched terms.
abstract	String	A short description of the extension.
dist	String	The name of the distribution in which the extension was last released.
version	SemVer	The version of the distribution release.
docpath	String	The path to the extension documentation in the distribution release, sans file name suffix.
date	Date	The date the release was uploaded to PGXN.
user	String	The nickname of the user who uploaded this release.
user_name	String	The full name of the user who uploaded this release.

Users Hits

Each hit when when searching the users index reflects a registered PGXN user. The hit objects contain the following keys:

Key	Type	Description
user	String	The nickname of the user.
name	String	The full name of the user.
excerpt	String	An excerpt from the user's details highlighting matched terms.
uri	String	The user's URI, if any.

Tags Hits

Each hit when when searching the tags index reflects a single tag. The hit objects contain the following keys:

Key	Type	Description
tag	String	The tag.

Perl Example

Assuming you have retrieved the JSON document from the index API and stored the data in the $table hash, you can fetch the JSON results for a documentation search for the string "test" like so:

use URI::Template;
use HTTP::Tiny;
use JSON;
my $tmpl = URI::Template->new('https://api.pgxn.org' . $table->{search});
my $uri = $tmpl->process({ in => 'docs' });
$uri->query_form({ q => 'test' });

my $req  = HTTP::Tiny->new;
my $res  = $req->get($uri);
my $dist = decode_json $res->{content};