InstaMaps Route API

openapi: 3.2.0
info:
  title: InstaMaps Route 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: Route
paths:
  /v1/plan_routes:
    post:
      operationId: plan_routes
      summary: Split up to 100 stops across up to 10 drivers from one depot, in the best order…
      description: 'Split up to 100 stops across up to 10 drivers from one depot and put each driver''s stops in the best order on real roads (Great Britain and US), within a shift length including time at each stop. Each driver gets google_maps_links: the day as chained Google Maps links of up to 9 stops each, every link starting where the last one ended (the Maps app takes about 10 stops a route), so a driver opens the first and then the next; plus google_maps_link_all_stops, one link with every stop, for a desktop browser. Stops that do not fit or cannot be reached come back in `unassigned` with the reason. A driver over the daily driving limits (EU/UK 9 hours, US 11) gets driving_limit_warning; low bridges under 4.6 m near a driver''s road come back as low_bridges (advisory). The map of each driver''s stops, numbered in order, shows in the chat by itself (no road line: the Google Maps links are the route). Set render to true only when the user wants to keep or share the map: it returns a link, GeoJSON and KML, and update_map can change it later. A kept route map carries each driver''s Google Maps links.


        Use when:

        - A day of deliveries, installs or visits

        - More than 10 stops (the Google Maps app limit)

        - Work that must fit a shift, with time at each stop


        Not for:

        - Single journeys: get_road_distances

        - Just the nearest site to each customer: filter_by_location


        Coverage: Great Britain and the US on our roads; elsewhere straight-line estimates, labelled.


        Reference: https://get-instamaps.com/mcp-server/tools/plan_routes'
      tags:
      - Route
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                depot:
                  description: 'Where the drivers start: an address or {lat, lng}.'
                stops:
                  type: array
                  minItems: 2
                  maxItems: 100
                  items: {}
                  description: Addresses, or {id, name, address} / {id, name, lat, lng}. name labels the stop on the map and in the plan.
                drivers:
                  type: integer
                  minimum: 1
                  maximum: 10
                  default: 1
                return_to_depot:
                  type: boolean
                  default: true
                shift_hours:
                  type: number
                  minimum: 1
                  maximum: 14
                  default: 8
                service_minutes:
                  type: number
                  minimum: 0
                  maximum: 120
                  default: 10
                  description: Time spent at each stop.
                render:
                  type: boolean
                  default: false
                  description: 'Also keep the map: a link to share with the drivers, GeoJSON and KML.'
                title:
                  type: string
                  description: The kept map's title when render is on.
                traffic:
                  type: string
                  enum:
                  - weekday
                  - free_flow
                  default: weekday
                  description: 'weekday (default): road times with the area''s measured weekday slowdown (DfT delay on local ''A'' roads by council and on motorways in Great Britain; the Urban Mobility Report''s Travel Time Index by US urban area). free_flow: empty roads.'
                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:
              - depot
            example:
              depot: Canning Town, London E16 1DQ
              stops:
              - id: '0'
                address: Stratford Station, London E15 1AZ
              - id: '1'
                address: Hackney Central, London E8 1LL
              - id: '2'
                address: Bethnal Green Road, London E2 6AH
              - id: '3'
                address: Bow Road, London E3 4DH
              - id: '4'
                address: Leyton High Road, London E10 5NA
              drivers: 1
      responses:
        '200':
          description: 'The answer. For example: "5 stops across 1 driver(s) · 1 of 5 high confidence (4 medium, 0 low). Caveats: street or named place (4 rows)."'
          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