# GSA eLibrary Search

## Overview

| Property | Value |
|----------|-------|
| **Status** | active |
| **Method** | `GET` |
| **Endpoint** | `/v2/gsaelibrary/search` |
| **Base URL** | `https://api.piloterr.com` |
| **Credit Cost** | 1 credit per call |
| **Documentation** | https://www.piloterr.com/library/gsaelibrary-search |

## Description

Search GSA eLibrary for schedule, SIN, and contract rows by keyword or by a full search URL.

## Authentication

- **Key Name:** `x-api-key`
- **Location:** HTTP Header
- **Get an API key:** https://app.piloterr.com/register

## Example Request

```bash
curl --location --request GET 'https://api.piloterr.com/v2/gsaelibrary/search' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### US RADAR INC

```json
{
  "results": [
    {
      "sin": null,
      "url": "https://www.gsaelibrary.gsa.gov/ElibMain/contractorInfo.do?contractNumber=GS-07F-0239T&contractorName=US+RADAR+INC&executeQuery=YES",
      "name": "US RADAR INC",
      "category": "Contractors",
      "description": null,
      "result_type": "contract",
      "schedule_name": "Multiple Award Schedule",
      "contract_number": "GS-07F-0239T",
      "schedule_number": "MAS"
    }
  ],
  "pagination": {
    "next": null,
    "page": 1,
    "per_page": 63,
    "total_pages": 1,
    "total_results": 63
  }
}
```

## Documentation

## Overview

Search the GSA eLibrary summary at gsaelibrary.gsa.gov. Send a keyword such as `radar`, or a full `searchResults.do` URL. The response is `{ results, pagination }`. Every row is a schedule, a SIN, or a contract.

A SIN row is either the category itself or a subgroup under that SIN. On a category row, `name` is the SIN title, such as `Purchasing of New Electronic Equipment`, and `sin` is the code, such as `33411`. On a subgroup row, `name` is the label printed on the link, such as `Airborne Radar Equipment`, `sin` stays the parent code, and `url` contains `subcategoryCode`.

A contract row carries the contractor name, the contract number, and a `contractorInfo.do` URL. That URL already includes the contractor name. Pass it to `/v2/gsaelibrary/contract`. A contract number on its own, such as `GS-07F-0239T`, is accepted by the contract endpoint and currently returns 404, because GSA asks for the contractor name that search puts in the URL.

## Quickstart

GET and POST take the same parameters. These examples use GET.

```
GET https://api.piloterr.com/v2/gsaelibrary/search?query=radar
GET https://api.piloterr.com/v2/gsaelibrary/search?query=https://www.gsaelibrary.gsa.gov/ElibMain/searchResults.do?searchText=radar&searchType=allWords
```

For `radar`, the summary includes the Multiple Award Schedule, SIN rows such as `334515`, subgroup rows such as `Airborne Radar Equipment`, and the contract `US RADAR INC` / `GS-07F-0239T`.

## Parameters

| Parameter | Required | Example |
|---|---|---|
| `query` | yes | `radar` |

`query` is required. A blank value returns 400. A URL whose host is not `gsaelibrary.gsa.gov` returns 400. A URL on that host must be a search results URL (`searchResults.do` or `searchText=`).

## Pagination

eLibrary returns this summary in one response. `pagination.page` is `1`. `pagination.next` is `null`. `pagination.total_results` is the number of rows parsed. `pagination.total_pages` is `1` when rows exist and `0` when the summary is empty. `pagination.per_page` matches that row count.

There is no second page to request. `next` stays `null` because the summary has no further page. URLs are unique on the page. The same `sin` code can appear on several subgroup rows, each with its own URL and label.

## Response fields

| Field | Type | Meaning |
|---|---|---|
| `results` | array | Schedule, SIN, and contract rows |
| `results[].result_type` | string | `schedule`, `sin`, or `contract` |
| `results[].name` | string | Schedule title, SIN title, subgroup label, or contractor name |
| `results[].url` | string | Absolute eLibrary URL |
| `results[].contract_number` | string or null | Contract number on contract rows |
| `results[].schedule_number` | string or null | Schedule code, such as `MAS` |
| `results[].schedule_name` | string or null | Schedule title |
| `results[].sin` | string or null | SIN code. On a subgroup this is the parent SIN |
| `results[].category` | string or null | Large category above the row, such as `Contractors` |
| `results[].description` | string or null | Scope text when the row prints one |
| `pagination.page` | integer | `1` |
| `pagination.per_page` | integer or null | Rows in this summary |
| `pagination.total_results` | integer | Same row count |
| `pagination.total_pages` | integer | `1` or `0` |
| `pagination.next` | null | No further page |

## Use cases

- A buyer looking up which MAS SIN covers ground-penetrating radar, and reading the subgroup label `Airborne Radar Equipment` instead of only the parent code `33411`.
- A capture manager checking that US RADAR INC appears as contract `GS-07F-0239T` and saving the `contractorInfo.do` URL for the contract call.
- A market-research pass that collects every unique schedule and SIN URL for the keyword `radar` from the single summary page.

## Error codes

| Code | Meaning |
|---|---|
| `400` | Empty `query`, or a URL outside gsaelibrary.gsa.gov |
| `401` | Missing API key |
| `404` | The page was not a search results summary |
| `500` | The fetch failed |

## Related endpoints

[GSA eLibrary Contract](https://www.piloterr.com/library/gsaelibrary-contract)