> ## Documentation Index
> Fetch the complete documentation index at: https://www.myhamlet.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# List locations

> Returns a cursor-paginated list of the locations your API key is entitled to, ordered by last update (oldest first) so you can sync incrementally. Page forward by passing the previous response's `next_cursor` as `cursor`. Pass `updated_since` to return only locations changed at or after that time; it composes with the cursor.



## OpenAPI

````yaml /openapi.json get /v1/locations
openapi: 3.1.0
info:
  title: Hamlet Public API
  version: 0.1.0
  description: >-
    Public API for programmatic access to Hamlet civic intelligence data:
    government meetings, transcripts, and related records from local
    governments.
servers:
  - url: https://api.myhamlet.com
    description: Production
security: []
paths:
  /v1/locations:
    get:
      tags:
        - Locations
      summary: List locations
      description: >-
        Returns a cursor-paginated list of the locations your API key is
        entitled to, ordered by last update (oldest first) so you can sync
        incrementally. Page forward by passing the previous response's
        `next_cursor` as `cursor`. Pass `updated_since` to return only locations
        changed at or after that time; it composes with the cursor.
      parameters:
        - schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
            description: Maximum number of items to return per page.
            example: 50
          required: false
          description: Maximum number of items to return per page.
          name: per_page
          in: query
        - schema:
            type: string
            description: >-
              Opaque pagination cursor from a previous response's `next_cursor`.
              Omit for the first page.
            example: eyJ1IjoiMjAyNi0wNS0wMSAxODoyMjoxMCIsImkiOjQyfQ
          required: false
          description: >-
            Opaque pagination cursor from a previous response's `next_cursor`.
            Omit for the first page.
          name: cursor
          in: query
        - schema:
            type: string
            format: date-time
            description: >-
              Inclusive lower bound on `updated_at` (ISO-8601 with a UTC `Z` or
              numeric offset, e.g. `2026-05-01T18:22:10Z`). Returns only records
              changed at or after this time, ordered and paged exactly like a
              normal request — pass it alongside `cursor` to sync incrementally.
              A malformed or offset-less timestamp returns `400`.
            example: '2026-05-01T18:22:10Z'
          required: false
          description: >-
            Inclusive lower bound on `updated_at` (ISO-8601 with a UTC `Z` or
            numeric offset, e.g. `2026-05-01T18:22:10Z`). Returns only records
            changed at or after this time, ordered and paged exactly like a
            normal request — pass it alongside `cursor` to sync incrementally. A
            malformed or offset-less timestamp returns `400`.
          name: updated_since
          in: query
      responses:
        '200':
          description: A page of entitled locations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocationList'
        '400':
          description: Invalid cursor or query parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
components:
  schemas:
    LocationList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Location'
        next_cursor:
          type:
            - string
            - 'null'
          description: >-
            Pass as `cursor` to fetch the next page; `null` when there are no
            more results.
          example: eyJ1IjoiMjAyNi0wNS0wMSAxODoyMjoxMCIsImkiOjQyfQ
      required:
        - data
        - next_cursor
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: not_found
            message:
              type: string
              example: The requested resource was not found.
          required:
            - code
            - message
      required:
        - error
    Location:
      type: object
      properties:
        uuid:
          type: string
          description: Public identifier.
          example: 5f2b0c3a-1d4e-4a8b-9f6d-2a1c3e4b5d6f
        type:
          type: string
          enum:
            - CITY
            - COUNTY
            - STATE
          description: Jurisdiction type.
          example: CITY
        name:
          type: string
          example: Palo Alto
        state_name:
          type: string
          example: California
        state_abbreviation:
          type: string
          description: Two-letter state code.
          example: CA
        county_names:
          type: array
          items:
            type: string
          description: Counties this location belongs to (for cities).
          example:
            - Santa Clara
        created_at:
          type: string
          description: ISO-8601 UTC timestamp.
          example: '2025-01-10T00:00:00.000Z'
        updated_at:
          type: string
          description: ISO-8601 UTC timestamp; drives the sync cursor.
          example: '2026-05-01T18:22:10.000Z'
      required:
        - uuid
        - type
        - name
        - state_name
        - state_abbreviation
        - county_names
        - created_at
        - updated_at
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````