Search.gov Home > APIs for Developers > Non-.gov URLs API

Helping the public find timely, needed government information and services on USA.gov—from all government websites.

Looking to review your agency’s websites in the list?

About the API

  • Overview

  • Using the API

  • Parameters

  • Data Sources

  • What it Returns

    Overview

    As the U.S. government’s official web portal, USA.gov and its Spanish counterpart GobiernoUSA.gov search across all federal, state, local, tribal, and territorial government websites. Most government websites end in .gov or .mil, but many end in .com, .org, .edu, or other top-level domains.

    This API allows you to tap into a list of all government URLs that don’t end in .gov or .mil. URLs are searchable by keyword, state, or scope.

    What’s Included in This List?

    What’s Not Included in This List?

    • .gov URLs
    • .mil URLs
    • Subdomains or folders that are already covered by a higher-level domain
    • State institutions of higher education or their board of regents
    • K-12 school districts
    • Local fire, library, police, sheriff, etc. departments with separate websites
    • Local chambers of commerce or visitor bureaus
    • Nonprofit municipal leagues or councils of government officials
    • Nonprofit historical societies
    • Transit authorities

    Using the API

    This API accepts a GET request.

    The base URL is http://govt-urls.api.usa.gov/government_urls/search?.

    Sample API requests follow.

    All known non-.gov URLs http://govt-urls.api.usa.gov/government_urls/search?scope_ids=usagov

    All known federal URLs http://govt-urls.api.usa.gov/government_urls/search?q=usagovFED

    All known URLs for villages http://govt-urls.api.usa.gov/government_urls/search?q=village

    All known URLs for villages in New York http://govt-urls.api.usa.gov/government_urls/search?q=village&states=NY

    All known URLs for New York and Pennsylvania http://govt-urls.api.usa.gov/government_urls/search?states=ny,pa

    Parameters

    Five parameters are accepted.

    1. q—Keyword or phrase for your search query. You also can use this field to specify which states or other preset scopes to use as a filter. For states and possessions, use usagov plus the U.S. Postal Service’s abbreviations for states or possessions (such as usagovAK for Alaska and usagovPR for Puerto Rico). The three other preset scopes are usagovFED (non-.gov URLs for federal agencies), usagovQUASI (quasi-governmental agencies or programs), and usagovNSN (Native Sovereign Nations).
    2. states—A comma-separated string specifying which states or possessions to use as a filter. The two-letter code is based on the Postal Service abbreviation.
    3. scope_ids—Use usagov to list all known non-.gov URLs.
    4. size—Specifies how many results are returned (up to 100 at a time).
    5. offset—Specifies the starting record.

    Combine parameters with &.

    Data Source

    The original, searchable database for these URLs is publicly available at http://govt-urls.usa.gov/tematres.

    We make periodic updates as we come across changes and welcome comments and additions. Submit a new issue to contribute directly to this list or email us at search@support.digitalgov.gov.

    What It Returns

    Below is a sample JSON response for http://govt-urls.api.usa.gov/government_urls/search?q=johnson+city.

    {
    total: 2,
    offset: 0,
    results: [
    {
    id: "5278",
    name: "johnsoncitytn.org",
    parents: [
    "usagovTN"
    ],
    states: [
    "TN"
    ],
    creation_date: "2013-06-06",
    last_modified_date: "2013-06-06",
    scope_note: "City of Johnson City, TN",
    scope_id: "usagov",
    related_terms: [ ],
    equivalent_related_terms: [ ],
    non_preferred_terms: [ ],
    preferred_terms: [ ]
    },
    {
    id: "9802",
    name: "villageofjc.com",
    parents: [
    "usagovNY"
    ],
    states: [
    "NY"
    ],
    creation_date: "2013-06-06",
    last_modified_date: "2013-06-06",
    scope_note: "Village of Johnson City, NY",
    scope_id: "usagov",
    related_terms: [ ],
    equivalent_related_terms: [ ],
    non_preferred_terms: [
    "johnsoncityny.org"
    ],
    preferred_terms: [ ]
    },
    {}
    ]
    } <a name="code-samples"></a>
    

    Fields not already mentioned above that deserve a bit more explanation include:

    • parents—indicates the category for each URL, such as federal (usagovFED) or state or possession (usagovAK, usagovPR, etc.).
    • scope_note—provides quick information about which government agency owns the URL and how it is used.
    • related_terms—indicates an association between two related terms when it seems helpful.
    • equivalent_related_terms—indciates two URLs that both resolve to the same website. Neither is preferred.
    • non_preferred_terms—indicates a nonpreferred URL. Nonpreferred URLs no longer resolve or redirect to another URL. non_preferred_terms is the reciprocal of preferred_terms and means “don’t use” the term following it.
    • preferred_terms—indicates the preferred, resolving URL. “Use” the term following it.

    Open Source Code

    The code that runs this API is on Github. If you’re a Rails developer, fork our Non-.gov URLs repo to add features (such as additional searchable fields) or fix bugs. Better yet, send us a pull request to contribute your changes to our project and improve this API for everyone who is using it.

    Feedback

    Email us at search@support.digitalgov.gov with any suggestions about what you’d like to see in the next version of this API.

    A Tip of the Hat

    A tip of the hat to Marilyn Kercher. She started this list many years ago and took it as her personal mission to ensure you can find information from any government website—including those that don’t end in .gov or .mil—when you search on USA.gov. She would be thrilled to learn that this list is now open for anyone to access.

    Terms of Use

    By accessing this API, you agree to USA.gov’s Terms of Service for Developer Resources.