# 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`: location `govtribe_id` values or location text.
  * `vendor_location_ids`: location `govtribe_id` values 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`.
* When you already have a nested location object from a prior search result, prefer its `govtribe_id` over repeating free-text.
* 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
{
  "place_of_performance_ids": ["Virginia"],
  "place_of_performance_ids_operator": "in"
}
```

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

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

Vendor location by ZIP: Tool: `Search_Vendors`

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

State filter by USPS code: Tool: `Search_State_And_Local_Contract_Opportunities`

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

Jurisdiction filter by FIPS code: Tool: `Search_State_And_Local_Contract_Opportunities`

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.govtribe.com/user-guide/mcp/guides/location_filtering_guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.