# phpman > perldoc > WWW::Search::FirstGov

## NAME
    [WWW::Search::FirstGov](https://www.chedong.com/phpMan.php/perldoc/WWW%3A%3ASearch%3A%3AFirstGov/markdown) - class for searching <http://www.firstgov.gov>

## SYNOPSIS
        use [WWW::Search](https://www.chedong.com/phpMan.php/perldoc/WWW%3A%3ASearch/markdown);
        my $search = new [WWW::Search](https://www.chedong.com/phpMan.php/perldoc/WWW%3A%3ASearch/markdown)('FirstGov'); # cAsE matters
        my $query = [WWW::Search::escape_query](https://www.chedong.com/phpMan.php/perldoc/WWW%3A%3ASearch%3A%3Aescapequery/markdown)("uncle sam");
        $search->native_query($query);
        while (my $result = $search->next_result()) {
          print $result->url, "\n";
        }

## DESCRIPTION
    Class specialization of [WWW::Search](https://www.chedong.com/phpMan.php/perldoc/WWW%3A%3ASearch/markdown) for searching <http://www.firstgov.gov>.

    FirstGov.gov can return up to 100 hits per page.

    This class exports no public interface; all interaction should be done through [WWW::Search](https://www.chedong.com/phpMan.php/perldoc/WWW%3A%3ASearch/markdown)
    objects.

## OPTIONS
    The following search options can be activated by sending a hash as the second argument to
### native_query

### Result Set Partitioning
    { 'begin_at' => '100' }
        Retrieve results starting at 100th match.

        This option is not passed to FirstGov.gov. Instead, this option is used to set 'offset',
        'act.next.x' and 'act.next.y' options to obtain results starting the requested starting
        point.

    { 'offset' => '100' }
        If 'act.next.x' and 'act.next.y' options are set, retrieve results starting at the 100th
        plus 1 plus the value of the 'nr' option. If 'act.prev.x' and 'act.prev.y' options are set,
        retrieve results starting at the 100th plus 1 less the value of the 'nr' option.

        Note: Do not use this option. Use the 'begin_at' option instead.

        Note: This option was named 'fr' in a past version of FirstGov.gov's search engine.

    { 'act.next.x' => '1', 'act.next.y' => '1' }
        Retrieve next set of results, starting at the value of the 'offset' option plus 1 plus the
        value of the 'nr' option.

        Note: Do not use this option.

    { 'act.prev.x' => '1', 'act.prev.y' => '1' }
        Retrieve previous set of results, starting at the value of the 'offset' option plus 1 less
        the value of the 'nr' option.

        Note: Do not use this option.

    { 'nr' => '40' }
        Retrieve 40 results.

        FirstGov.gov returns no more than 100 results at a time.

        From FirstGov.gov documentation:

        The Number of Results parameter (nr) allows you or the user to set how many search "hits"
        appear on each search results page. If this parameter is not used, nr is defaulted to 10.

### Query Terms
    From FirstGov.gov documentation:

    You may have noticed many parameters are suffixed by the number zero (0). This number
    essentially groups a set of search parameters sharing the same suffix number together to form a
    query statement. It is possible to link two or more such statements together. You might have
    guessed that this is accomplished by creating another set of search parameters, this time
    suffixed by the number one (1) or higher. Just be careful to keep track of parameters and follow
    the same guidelines as outline above. For example if you have an mw0, have corresponding ms0,
    mt0, etc. parameters. For each mw1, set its own corresponding ms1, mt1, etc. parameters. Be
    forewarned that the more complicated the query, the longer it may take to process.

    { 'mw0' => 'uncle sam' }
        Return results that contain the words 'uncle' and 'sam'.

        The native_query() method sets this option.

        [WWW::Search::FirstGov](https://www.chedong.com/phpMan.php/perldoc/WWW%3A%3ASearch%3A%3AFirstGov/markdown) defaults the mw0 option to an empty string.

        Note: Do not use the 'mw0' option, instead use the native_query() method and the 'mw1',
        'mw2', ... options.

        From FirstGov.gov documentation:

        The Main Words parameter is represented by the input field named mw0. This is a text input
        field that allows a user to enter the word or words they would like to search for.

    { 'mt0' => 'all' }
    { 'mt0' => 'any' }
    { 'mt0' => 'phrase' }
        [WWW::Search::FirstGov](https://www.chedong.com/phpMan.php/perldoc/WWW%3A%3ASearch%3A%3AFirstGov/markdown) defaults the mt0 option to 'all'.

        From FirstGov.gov documentation:

        The Main Type field (mt0) is used to specify how you want to search for the words entered in
        the mw0 field. You can search for documents containing all the words provided, any of the
        words provided, or documents containing the exact phrase in the order the words are entered.
        This is done by setting the mt0 field to "all", "any", or "phrase". If this field is not
        provided, it is defaulted to "all".

    { 'ms0' => 'should' }
    { 'ms0' => 'mustnot' }
    { 'ms0' => 'must' }
        [WWW::Search::FirstGov](https://www.chedong.com/phpMan.php/perldoc/WWW%3A%3ASearch%3A%3AFirstGov/markdown) defaults the ms0 option to 'must'.

        From FirstGov.gov documentation:

        Main Sign field (ms0) further specifies your search. It can be used to specify whether words
        should or must not be present in the document. This is done by setting the ms0 field to
        "should" or "mustnot". If this field is not provided, it is defaulted to "should".

    { 'in0' => 'any' }
    { 'in0' => 'title' }
    { 'in0' => 'url' }
        Note: The value 'anywhere' was used in place of 'any' in a past version of FirstGov.gov's
        search engine. The value 'home' used in a past version of FirstGov.gov's search engine is
        obsolete.

        From FirstGov.gov documentation:

        The In parameter (in0) can be implemented to tell the search engine where specifically to
        search. Setting in0 to "anywhere" searches the complete web page of all web pages in a
        particular database. [...] Setting in0 to "title" searches only the Titles of web pages of a
        particular database.

    { 'in0' => 'domain', 'dom0' => 'doc.gov noaa.gov', 'domToggle' => ' +(' }
    { 'in0' => 'domain', 'dom0' => 'doc.gov noaa.gov', 'domToggle' => ' -(' }
        The query is limited to searching the doc.gov and noaa.gov domains when the doToggle option
        is set to ' +(' (note leading space). The query is limited to searching all but the doc.gov
        and noaa.gov domains when the doToggle option is set to ' -(' (note leading space).

        From the FirstGov.gov documentation:

        Setting in0 to "domain" allows you to search only a certain domain or domains, or
        domain/path combinations. Use of this attribute also requires an additional parameter, the
        Domain parameter (dom0). The Domain parameter (dom0), when used with in0="domain", allows
        searching of specific domains or domain/path combinations as described above. This is useful
        if you want a "site search" for your website. To do this, you could set in0 to domain and
        then dom0 to yourdomain.com. This would ensure that users are only searching web pages
        within your domain. In fact, you may specify as many domain or domain/path combinations up
        to 20 that you would like to limit your searches to. You can use any combination of domains
        or domain/path elements as long as they are separated by a comma or a space.

    { 'rs' => '1' }
        Results will include variations (example: vote, voting).

    { 'doc' => '' }
    { 'doc' => 'text/html' }
    { 'doc' => 'application/pdf' }
    { 'doc' => 'text/xml' }
    { 'doc' => 'application/msword' }
    { 'doc' => 'application/vnd.ms-excel' }
    { 'doc' => 'application/vnd.ms-powerpoint' }
    { 'doc' => 'text/plain' }
        Restrict results to a type of document.

    { 'age' => 'any' }
    { 'age' => '1m' }
    { 'age' => '3m' }
    { 'age' => '6m' }
    { 'age' => '9m' }
    { 'age' => '1y' }
        Restrict results to date document was updated.

    { 'sop' => '<', 'siz' => '512', 'byt' => 'b' }
        Restrict results to documents less than 512 bytes.

        The attribute sop may be set to '<' or '>'. The attribute 'byt' may be set to 'b', 'kb', or
        'mb'.

    { 'lang' => '' }
        The query is not limited by language.

        To limit a query to documents of a specific language, set this option to one of FirstGov's
        language abbreviations (an empty string denotes "Any language"): af - Afrikaans, sq -
        Albanian, ar - Arabic, eu - Basque, be - Byelorussian, bg - Bulgarian, ca - Catalan, tzh -
        Chinese (trad), szh - Chinese (simp), hr - Croatian, cs - Czech, da - Danish, nl - Dutch, en
        - English, et - Estonian, fo - Faeroese, fi - Finnish, fr - French, fy - Frisian, gl -
        Galician, de - German, el - Greek, he - Hebrew, hu - Hungarian, is - Icelandic, id -
        Indonesian, it - Italian, ja - Japanese, ko - Korean, la - Latin, lv - Latvian, lt -
        Lithuanian, ms - Malay, no - Norwegian, pl - Polish, pt - Portuguese, ro - Romanian, ru -
        Russian, sk - Slovak, sl - Slovenian, es - Spanish, sv - Swedish, th - Thai, tr - Turkish,
        uk - Ukrainian, vi - Vietnamese, cy - Welsh

  Specifying Federal and/or State Government Databases
    { 'db' => 'www' }
        Note: The db and st options have been merged into the the db option in the current version
        of FirstGov.gov's search engine. The value 'states' now specifies searches against all
        states.

        From FirstGov.gov documentation:

        The Database field (db) allows you to specify if a search should query Federal Government
        websites, State Government websites, or both. This is done by setting db to "www" for a
        Federal Search, setting db to "states" for a State Search, or "www-fed-all" to search both.
        [...] If the db field is not provided, it is defaulted to Federal.

        List of State and Territory Abbreviations for FirstGov Searching: AS - All States, AL -
        Alabama, AK - Alaska, AZ - Arizona, AR - Arkansas, CA - California, CO - Colorado, CT -
        Connecticut, DC - D.C., DE - Delaware, FL - Florida, GA - Georgia, HI - Hawaii, ID - Idaho,
        IL - Illinois, IN - Indiana, IA - Iowa, KS - Kansas, KY - Kentucky, LA - Louisiana, ME -
        Maine, MD - Maryland, MA - Massachusetts, MI - Michigan, MN - Minnesota, MS - Mississippi,
        MO - Missouri, MT - Montana, NE - Nebraska, NV - Nevada, NH - New Hampshire, NJ - New
        Jersey, NM - New Mexico, NY - New York, NC - North Carolina, ND - North Dakota, OH - Ohio,
        OK - Oklahoma, OR - Oregon, PA - Pennsylvania, RI - Rhode Island, SC - South Carolina, SD -
        South Dakota, TN - Tennessee, TX - Texas, UT - Utah, VT - Vermont, VA - Virginia, WA -
        Washington, WV - West Virginia, WI - Wisconsin, WY - Wyoming, SA - American Samoa, GU -
        Guam, MP - Mariana Islands, MH - Marshall Islands, FM - Micronesia, PR - Puerto Rico, VI -
        Virgin Islands.

### Result Presentation
    { 'rn' => '2' }
        Request FirstGov.gov to return pages using affiliate #2's page format.

        This option is used by FirstGov.gov to return result pages customized with headers and
        footers for the affiliate as identified by the 'rn' option.

        When not set, FirstGov.gov currently sets the 'rn' parameter to '2'.

        Note: It is suggested that this option not be used (since this class was developed using
        results returned with the 'rn' option not set).

        From FirstGov.gov documentation:

        The Referrer Name (rn) field is used to uniquely identify your affiliate. Each Affiliate,
        upon registration, is assigned a referrer ID that corresponds to it.

    { 'srt' => '' }
        Sort results by relevance (FirstGov.gov's default).

        Additional values are: 8 (Date - ascending), 7 (Date - descending), 6 (Size - ascending),
        and 5 (Size - descending).

    { 'dsc' => 'det' }
    { 'dsc' => 'sum' }
        Whether ('det') or not ('sum') to highlight search terms in result summaries.

### Other Options
    { 'parsed' => 'true' }
        The default behavior for FirstGov.gov's search engine is to parse all search requests, and,
        if any options are missing or deprecated, rewrite the options and redirect the browser back
        to FirstGov.gov. When the parsed option is set to "true", FirstGov.gov does not perform this
        action.

    { 'sp' => '1' }
        Check spelling of the query terms. FirstGov.gov will return a message and a resubmit buttion
        if it finds misspelled query terms.

        Note: [WWW::Search::FirstGov](https://www.chedong.com/phpMan.php/perldoc/WWW%3A%3ASearch%3A%3AFirstGov/markdown) does not parse the results for this option.

    { 'submit' => 'Search' }
        Submit button.

    { 'md' => 'adv' }
        Function is unknown.

## SEE ALSO
    To make new back-ends, see [WWW::Search](https://www.chedong.com/phpMan.php/perldoc/WWW%3A%3ASearch/markdown), or the specialized AltaVista searches described in
    options.

    An email list is for notifying users of updates to Perl's [WWW::Search::FirstGov](https://www.chedong.com/phpMan.php/perldoc/WWW%3A%3ASearch%3A%3AFirstGov/markdown) module is
    avilalable at <http://two.pairlist.net/mailman/listinfo/www-search-firstgov> . It is meant to be a
    very low volume list that only notifies users when there is a new version of the module
    available, and possibly when changes to the FirstGov search engine have broken the latest
    version of the module.

HOW DOES IT WORK?
    "native_setup_search" is called before we do anything. It initializes our private variables
    (which all begin with underscores) and sets up a URL to the first results page in "{_next_url}".

    "native_retrieve_some" is called (from "[WWW::Search::retrieve_some](https://www.chedong.com/phpMan.php/perldoc/WWW%3A%3ASearch%3A%3Aretrievesome/markdown)") whenever more hits are
    needed. It calls the LWP library to fetch the page specified by "{_next_url}". It parses this
    page, appending any search hits it finds to "{cache}". If it finds a ``next'' button in the
    text, it sets "{_next_url}" to point to the page for the next set of results, otherwise it sets
    it to undef to indicate we're done.

## SUPPORT
    Send questions, comments, suggestions, and bug reports to <<dsutch@doc.gov>>.

    To be notified of updates to [WWW::Search::FirstGov](https://www.chedong.com/phpMan.php/perldoc/WWW%3A%3ASearch%3A%3AFirstGov/markdown), subscribe to the update notification list at
    <http://two.pairlist.net/mailman/listinfo/www-search-firstgov>

## AUTHOR
    "[WWW::Search::FirstGov](https://www.chedong.com/phpMan.php/perldoc/WWW%3A%3ASearch%3A%3AFirstGov/markdown)" is written and maintained by Dennis Sutch - <<dsutch@doc.gov>>.

## LEGALESE
    THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
    WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    PURPOSE.

## BUGS
    None reported.

## VERSION HISTORY
    1.14 2003-04-08 - Updated parsing. Documented new search parameters. 1.13 2002-06-04 - Updated
    Makefile.PL to reflect requirement for [WWW::Search](https://www.chedong.com/phpMan.php/perldoc/WWW%3A%3ASearch/markdown) version 2.33. Rewrote tests to use
    [WWW::Search::Test](https://www.chedong.com/phpMan.php/perldoc/WWW%3A%3ASearch%3A%3ATest/markdown). 1.12 2002-06-03 - Updated to reflect changes to FirstGov (on 2002 Jun 03 they
    switched to a new search engine built by Fast Search & Transfer of Oslo, Norway). * The
    native_query options 'fr' and 'st' are obsolete. * the native_query option 'in0' now accepts the
    value 'any' instead of 'anywhere', and the value of 'home' is obsolete. Removed redefined
    [WWW::Search](https://www.chedong.com/phpMan.php/perldoc/WWW%3A%3ASearch/markdown) functionality.

    1.11 2002-03-13 - Updated to reflect changed FirstGov search engine parameters.
### approximate_result_count
    is "more than X relevant results". Changed test case 4 (in test.pl) to finish sooner.

    1.10 2002-03-05 - Updated to handle new FirstGov search engine format and to use
    [HTML::TreeBuilder](https://www.chedong.com/phpMan.php/perldoc/HTML%3A%3ATreeBuilder/markdown). Fixed problem that caused one too many searches against FirstGov.gov.
    Documented additional options, including adding notes from FirstGov.gov documentation.

    1.04 2001-07-16 - Fixed parsing problem.

    1.03 2001-03-01 - Removed 'require 5.005_62;'.

    1.02 2001-03-01 - Removed 'my' declarations for package variables.

    1.01 2001-02-26 - Fixed problem with quoted sring on MSWin. Removed 'our' declarations.

    1.00 2001-02-23 - First publicly-released version.