# Location\_Filtering\_Guide

## Purpose

Use this guide to set location filters correctly in GovTribe `Search_*` tools when fields accept different location value types. Use it when:

* the user asks for place-of-performance, vendor-location, state, county, city, or ZIP-scoped results.
* the schema includes fields like `place_of_performance_ids`, `vendor_location_ids`, `state_ids`, or `jurisdiction_ids`.

## Construction Rules

### Field and Value Shape

* Always check the selected tool schema; do not assume all location-like fields behave the same.
* Use the right value shape by field:
  * `place_of_performance_ids`: GovTribe location IDs or location text.
  * `vendor_location_ids`: GovTribe location IDs or location text.
  * `state_ids`: GovTribe state IDs or USPS codes (for example `VA`).
  * `jurisdiction_ids`: GovTribe jurisdiction IDs or FIPS codes.

### Operator Usage

* Use `<filter_key>_operator` when available:
  * `in` includes matches.
  * `not_in` excludes matches.

### Text Geocoding Behavior

* Location text is geocoded for `place_of_performance_ids` and `vendor_location_ids`.
* Matching is US-biased for ambiguous place names.
* Supported text categories are:
  * country
  * locality (city)
  * postal code
  * administrative area level 1 (state/territory)
  * administrative area level 2 (county)
* Do not send generic place-name text to `state_ids` or `jurisdiction_ids`; those fields expect IDs/codes, not free-text geocoding.

## Examples

Place-of-performance by state text: Tool: `Search_Federal_Contract_Opportunities`

```json
{
  "query": "",
  "place_of_performance_ids": ["Virginia"],
  "place_of_performance_ids_operator": "in"
}
```

Exclude one place-of-performance location: Tool: `Search_Federal_Contract_Opportunities`

```json
{
  "query": "",
  "place_of_performance_ids": ["California", "TX"],
  "place_of_performance_ids_operator": "not_in"
}
```

Vendor location by ZIP: Tool: `Search_Vendors`

```json
{
  "query": "",
  "vendor_location_ids": ["20001"]
}
```

State filter by USPS code: Tool: `Search_State_And_Local_Contract_Opportunities`

```json
{
  "query": "",
  "state_ids": ["VA"],
  "state_ids_operator": "in"
}
```

Jurisdiction filter by FIPS code: Tool: `Search_State_And_Local_Contract_Opportunities`

```json
{
  "query": "",
  "jurisdiction_ids": ["51059"],
  "jurisdiction_ids_operator": "in"
}
```