> ## 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 relevance-ranked with records-bearing places first. Paging walks the matches for a query, not a category — use /api/tools/v1/places/list to enumerate a jurisdiction. 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. ## OpenAPI ````yaml /openapi/tools-v1.yaml post /api/tools/v1/places/search openapi: 3.1.0 info: title: Govly Tools API 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: Shares description: Share opportunities, awards, and contacts with colleagues by email. - 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 relevance-ranked with records-bearing places first. Paging walks the matches for a query, not a category — use /api/tools/v1/places/list to enumerate a jurisdiction. 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. 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. A bare foreign code such as "JP" scopes overseas military installations. 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. Place search reports a periodically refreshed indexed value while place list computes it from live data, so the two can briefly disagree — treat list as authoritative. 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 ````