> ## Documentation Index > Fetch the complete documentation index at: https://docs.govly.com/llms.txt > Use this file to discover all available pages before exploring further. # Resolve place names to canonical Place ids > Resolve a place name to canonical Govly Place ids — counties, municipalities, states, ZIP codes, school districts, military installations, and countries. Results are ordered records-bearing first; hasRecords false means the place exists in the gazetteer but matches no opportunities or awards, so filtering by it returns nothing. nameMatch reports how the name matched: treat semantic as a prompt to confirm with the user, since vernacular geography such as "the Bay Area" has no canonical record and resolves to the nearest thing. partial is expected for county and municipality lookups, because canonical names carry a category suffix. isoCodes matches the place's own code exactly and is not a hierarchy — "US" matches only the country record, so use "US-XX" to scope inside a state, while a bare foreign code such as "JP" correctly scopes overseas military installations. Place ids are market-agnostic, but opportunity and award searches are market-scoped, so a returned id may not be searchable under the caller's subscription. Results are relevance-ranked and cursor-paginated: pass meta.nextCursor back as cursor until it is absent. Paging walks the matches for a query, it does not enumerate a category — no text query matches all 58 California counties. ## OpenAPI ````yaml /openapi/tools-v1.yaml post /api/tools/v1/places/search openapi: 3.1.0 info: title: Govly Tools API (Alpha) version: 1.0.0-alpha description: > ALPHA / UNSTABLE: This API is still in active development. Endpoint behavior, request fields, response fields, error codes, and operation names may change before the Tools API is declared stable. REST-callable tool surface for agent and automation workflows. Agents are the primary consumer, but integrations can be built on this API. Responses are JSON for typed clients; MCP tools may render action results into text-oriented formats separately. servers: - url: https://app.govly.com security: - bearerApiKey: [] - headerApiKey: [] tags: - name: Opportunities description: Search, fetch, and inspect Govly opportunity records. - name: Awards description: Search and inspect awarded government contracts. - name: Contacts description: Search and inspect government points of contact. - name: Signals description: Search clustered procurement and market intelligence signals. - name: Places description: Resolve place names to canonical Govly Place ids. - name: Product Catalogs description: List government contract price lists and search their line items. - name: Workspaces description: Create, update, and inspect opportunity workspaces. - name: Workspace Members description: Add users and teams to workspaces. - name: Workspace Attachments description: List and upload workspace attachments. - name: Workspace Comments description: Post comments to workspaces. - name: Follows description: Follow opportunities and related workspace activity. - name: Saved Searches description: List saved opportunity searches and cached matches. - name: Documents description: >- Read document representations and request temporary original-file downloads. - name: Quote Submissions description: >- Inspect quote submission requirements, submit quotes, and poll submission status. - name: Inbox description: Read and triage the authenticated user's matched inbox items. paths: /api/tools/v1/places/search: post: tags: - Places summary: Resolve place names to canonical Place ids description: > Resolve a place name to canonical Govly Place ids — counties, municipalities, states, ZIP codes, school districts, military installations, and countries. Results are ordered records-bearing first; hasRecords false means the place exists in the gazetteer but matches no opportunities or awards, so filtering by it returns nothing. nameMatch reports how the name matched: treat semantic as a prompt to confirm with the user, since vernacular geography such as "the Bay Area" has no canonical record and resolves to the nearest thing. partial is expected for county and municipality lookups, because canonical names carry a category suffix. isoCodes matches the place's own code exactly and is not a hierarchy — "US" matches only the country record, so use "US-XX" to scope inside a state, while a bare foreign code such as "JP" correctly scopes overseas military installations. Place ids are market-agnostic, but opportunity and award searches are market-scoped, so a returned id may not be searchable under the caller's subscription. Results are relevance-ranked and cursor-paginated: pass meta.nextCursor back as cursor until it is absent. Paging walks the matches for a query, it does not enumerate a category — no text query matches all 58 California counties. operationId: search_places requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - query properties: query: type: string maxLength: 200 description: The place name to resolve, such as "redstone arsenal". categories: type: array items: type: string enum: - postal_code - county - municipality - region - country - military_installation - school_district description: >- Restrict to these place categories, to disambiguate a name shared across categories. isoCodes: type: array items: type: string description: > Restrict to these jurisdiction codes, matched exactly (e.g. US-NC). Not hierarchical — "US" matches only the country record. cursor: type: string description: > Opaque cursor from the previous response's meta.nextCursor. Omit for the first page. Only valid for the exact query, categories, and isoCodes that produced it. perPage: type: integer default: 25 maximum: 100 description: Results per page. Default 25, maximum 100. responses: '200': description: Matching places content: application/json: schema: type: object required: - data - meta properties: data: type: array items: $ref: '#/components/schemas/Place' meta: $ref: '#/components/schemas/PlaceSearchMeta' '400': $ref: '#/components/responses/Error' '401': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' components: schemas: Place: type: object description: A canonical Govly Place, resolved from a name. required: - id - name - category - jurisdictionIsoCode - hasRecords properties: id: type: string description: > Govly Place id, as a string. Matches the ES place_ids keyword field directly, so it can be used as a filter value without conversion. name: type: string category: type: string enum: - postal_code - county - municipality - region - country - military_installation - school_district jurisdictionIsoCode: type: string description: The place's own ISO 3166-1 or 3166-2 code, e.g. US or US-NC. hasRecords: type: boolean description: > False means the place is in the gazetteer but matches no opportunities or awards, so filtering by its id returns nothing. nameMatch: type: string enum: - exact - partial - semantic description: > How the name matched. Optional — omitted entirely when not applicable. semantic means the query did not really match and this is the nearest record; confirm before filtering on it. partial is expected for county and municipality lookups, whose canonical names carry a suffix. PlaceSearchMeta: type: object description: Cursor-paginated result metadata for place search. required: - perPage - returned properties: perPage: type: integer description: Effective page size after clamping. Default 25, maximum 100. returned: type: integer description: Places returned on this page. nextCursor: type: string nullable: true description: > Pass back as cursor for the next page. Absent when there are no more matches, and also withheld in the rare case where semantic scoring failed mid-query and the results were served from lexical ranking — restart the search rather than paging on. ErrorEnvelope: type: object required: - errors properties: errors: type: array items: type: object required: - status - code - title - detail properties: status: type: string code: type: string title: type: string detail: type: string source: type: object properties: pointer: type: string responses: Error: description: Error response content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' securitySchemes: bearerApiKey: type: http scheme: bearer bearerFormat: API key headerApiKey: type: apiKey in: header name: X-API-KEY ````