InstaMaps Ask a table API

openapi: 3.2.0
info:
  title: InstaMaps Ask a table API
  version: 0.6.0
  description: 'Location data for lists, as one REST endpoint per job: geocode with a confidence per row, straight-line and road distances,

    multi-driver route plans, drive-time areas, official facts (census tract, HUBZone, flood zones), flood, crime and natural-hazard

    risk, live warnings, places nearby, plain-English questions over a table, and hosted maps. Strongest in the US and Great Britain,

    on our own address index, roads and official data. The same tools as the InstaMaps MCP server, as plain HTTP.


    **Auth.** Authorization: Bearer (or X-API-Key). Keys are free: sign in with Google at /developers/portal.


    **Free.** 2,500 lookups a day per account, every endpoint, reset at midnight UTC. No card.


    **What counts as a lookup.**

    - One lookup per row a call carries: an address placed, a journey measured, a stop routed, a place checked.

    - A question to ask_table is 10 lookups, however long the table.

    - A drive-time area is 10 lookups a band, plus one per place checked against it.

    - Maps, live hazards and postcode-radius lists are one lookup a call. Checking a background job (get_job) is free.

    - Rows sent by reference (a Google Sheet, a Drive file or an earlier run) are counted from the answer.


    **Keep what you get.** No 30-day cache rule: store the results in your own database for as long as you like. Every answer names its sources and their dates.


    **Every answer:**

    - Nothing is dropped: every row sent comes back, in order, under your own id; rows that cannot be placed or answered say why. An answer that would lose rows fails loudly instead.

    - Every row carries confidence {level: high | medium | low, score, basis}; basis is a stable code (rooftop, postcode_centre, not_placed…) and the answer''s confidence object says what each basis present means and what to do about it.

    - Every row carries record_key, the same place ID from every tool, so answers from different tools join on it.

    - Every answer ends with a run block: when, how many rows, sources with their dates, the confidence counts, calls used and left today, and a run_id that any tool can take as source {run} and render_map as from_run.

    - Lists by reference: pass a Google Sheet, a Drive file or a run_id instead of typing rows. Every tool but one only reads; write_to_sheet puts an answer into the sheet as new dated columns or a new tab, never overwriting.

    - No vendor or model names in answers; every source is named with its date.


    Docs: https://get-instamaps.com/developers'
  contact:
    name: InstaMaps
    email: hello@get-instamaps.com
    url: https://get-instamaps.com/developers
  termsOfService: https://get-instamaps.com/terms
servers:
- url: https://get-instamaps.com
  description: InstaMaps
security:
- apiKey: []
tags:
- name: Ask a table
paths:
  /v1/ask_table:
    post:
      operationId: ask_table
      summary: Answer a plain-English question about a whole table (filters, counts, distances…
      description: 'Answer a plain-English question about a table of rows (up to 5,000): filters ("open jobs in Leeds due this week", "accounts with no rep"), place questions ("customers within 5 miles of Manchester", "sites with 3+ pharmacies within 1 km", "in a flood zone", "high crime areas"), ranking, counts and group-bys ("homes by agent", "average price by area"), and two-list questions with reference_records ("customers within 10 km of any depot in the reference list"). Deterministic: the question is read into rules and tools, never answered by a model making up values, and `reading` says exactly how it was read. The first 200 matching rows come back in mode rows; past that use mode match. A zero result comes with a diagnosis (which part emptied it and the nearest non-empty reading). mode rows (default) returns the matching rows; match returns one TRUE/FALSE per input row in order (best for big tables: join it back in your own code); why returns the reading. Rows without lat/lng are placed from an address column when the question needs places. Place tools (nearby, crime, busy) cover the UK; flood covers England and the US.


        Use when:

        - "Overdue or fault jobs within 5 miles of the Enfield depot"

        - Counts and breakdowns over thousands of rows without writing formulas

        - A question mixing column filters with places


        Not for:

        - Placing addresses: geocode_batch

        - Planning visits: plan_routes


        Coverage: Any table; place questions use our UK and US geography.


        Reference: https://get-instamaps.com/mcp-server/tools/ask_table'
      tags:
      - Ask a table
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                question:
                  type: string
                  description: The question, as a person would ask it.
                records:
                  type: array
                  maxItems: 5000
                  items:
                    type: object
                  description: The table as row objects (keys are the column names).
                headers:
                  type: array
                  items:
                    type: string
                  description: Or the column names…
                rows:
                  type: array
                  maxItems: 5000
                  items:
                    type: array
                  description: …and the rows as arrays in the same order.
                mode:
                  type: string
                  enum:
                  - rows
                  - match
                  - why
                  default: rows
                reference_records:
                  type: array
                  items:
                    type: object
                  description: Optional second list for two-list questions (depots, competitors, stores).
                source:
                  type: object
                  description: 'Instead of typing rows: { sheet: "<Google Sheets link>", tab?: "Sites" } (shared with the InstaMaps service account, or viewable by anyone with the link), { file: "<Drive link to a CSV or Excel file>" }, or { run: "<run_id from an earlier answer>" }. Columns are found by their headers (id, name, address or its parts, lat/lng); name them if they aren''t obvious (id_column, address_column, lat_column, lng_column; from_column and to_column for road distances). Rows with coordinates are used as they are.'
                  properties:
                    sheet:
                      type: string
                    tab:
                      type: string
                    range:
                      type: string
                      description: e.g. "A1:H501"; the first row is the header.
                    file:
                      type: string
                    run:
                      type: string
                    id_column:
                      type: string
                    name_column:
                      type: string
                    address_column:
                      type: string
                    lat_column:
                      type: string
                    lng_column:
                      type: string
                    from_column:
                      type: string
                    to_column:
                      type: string
              required:
              - question
            example:
              question: Which accounts have annual revenue over 50k?
              records:
              - Account: Rice University
                Address: 6100 Main St Houston TX 77005
                Annual revenue: 82000
              - Account: Museum of Fine Arts
                Address: 1001 Bissonnet St Houston TX 77005
                Annual revenue: 23000
              - Account: Toyota Center
                Address: 1510 Polk St Houston TX 77002
                Annual revenue: 61000
      responses:
        '200':
          description: 'The answer. For example: "Read as: Annual revenue > 50,000. 2 of 3 rows match"'
          headers:
            X-Lookups-Used:
              schema:
                type: integer
              description: Lookups this call cost.
            X-Lookups-Remaining:
              schema:
                type: integer
              description: Free lookups left today.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: The answer in one or two sentences.
                additionalProperties: true
        '400':
          description: The request could not be answered; error says why.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
        '401':
          description: No API key, or an unknown or revoked one.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
        '404':
          description: No such endpoint.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
        '429':
          description: Today's free lookups are used up (or the call needs more than are left), or too many requests a minute.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
components:
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: im_live_…
      description: 'Authorization: Bearer <your API key> (or X-API-Key). Keys are free: sign in with Google at /developers/portal.'
externalDocs:
  description: Docs, pricing and examples
  url: https://get-instamaps.com/developers