InstaMaps Place API

openapi: 3.2.0
info:
  title: InstaMaps Place 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: Place
paths:
  /v1/geocode_batch:
    post:
      operationId: geocode_batch
      summary: Turn a list of addresses, business names, postcodes or coordinates into points…
      description: 'Place up to 100 addresses in one call. Each record comes back with a status (placed, review, unplaced), the location and its precision (rooftop, interpolated, street, postcode, town), a confidence with the evidence behind it (the score is our estimate of how often an answer that sure is right, being refitted against public address records; the same input always gets the same answer), the address quality, the admin parts (street, city, county, state, postcode, country), a stable record_key and the map version, and where one is close enough to be sure, the building at the point (residential or not: house, business, farm…). Coordinates in any common format ("53.8008, -1.5491", 51°30''03"N 0°07''40"W, "48.8584 N 2.2945 E"), or records with lat and lng, are placed as given and come back with the address at the point (nearest_address and the admin parts): this is also how to turn coordinates into addresses. Flats, units and suites are matched to their building. Every row carries its address parts (admin: house number, street, city, county, state, postcode, country); format "csv" also returns them as CSV to save in Drive or a sheet, and write_to_sheet puts them in the sheet as columns. Every row sent comes back in the order sent: unplaced rows with the reason, and rows past 100 as not looked up.


        Use when:

        - A list of addresses needs coordinates before anything else happens

        - You need to know how sure each placement is before trusting it

        - You want a sheet-ready table (format: "csv") with city, county, state, postcode, UK council and UPRN


        Not for:

        - Distances or "who is near what": filter_by_location, get_road_distances

        - Finding businesses of a kind around a place: find_nearby


        Coverage: Strongest in the US and Great Britain (house-level address data); council and UPRN in Great Britain. Partial address data for Canada, Germany, France, Spain, the Netherlands, Australia, Brazil and Mexico. Elsewhere many addresses come back unplaced, with the reason; coordinates work anywhere.


        Reference: https://get-instamaps.com/mcp-server/tools/geocode_batch'
      tags:
      - Place
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                addresses:
                  type: array
                  items:
                    type: string
                  maxItems: 100
                  description: Addresses, one per row.
                records:
                  type: array
                  maxItems: 100
                  description: Or rows with your own ids.
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                      address:
                        type: string
                    required:
                    - address
                format:
                  type: string
                  enum:
                  - json
                  - csv
                  default: json
                  description: 'csv: also return every row as CSV text (csv), one line per row in the order sent, to save as a file in Drive or paste into a sheet.'
                columns:
                  type: array
                  items:
                    type: string
                    enum:
                    - lat
                    - lng
                    - status
                    - address
                    - house_number
                    - street
                    - city
                    - county
                    - state
                    - postcode
                    - country
                    - precision
                    - score
                    - confidence
                    - why
                    - building
                    - reason
                    - council
                    - uprn
                    - record_key
                    - map_version
                  description: 'The fields for the CSV and for write_to_sheet, in order (CSV default: status, lat, lng, precision, confidence, reason, house_number, street, city, county, state, postcode, country, council, uprn, record_key; write_to_sheet default: lat, lng, status, address, city, county, state, postcode, country, precision, confidence). ID and input always lead the CSV. council (Great Britain: the local authority) and uprn (Great Britain: the nearest UPRN to a pin on a building, within 15 m) are blank elsewhere.'
                background:
                  type: boolean
                  description: 'With source: run as a background job and answer at once with job_id (automatic past 100 rows). Check with get_job; write_to_sheet with the job_id puts the results in the sheet as they finish.'
                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
            example:
              records:
              - id: hq
                address: 10 Downing Street, London SW1A 2AA
              - id: wh
                address: 1600 Pennsylvania Ave NW, Washington DC 20500
              - id: x
                address: asdfgh
      responses:
        '200':
          description: 'The answer. For example: "3 rows: 2 placed, 0 to review, 1 unplaced · 2 of 3 high confidence (0 medium, 1 low). Caveats: not placed (1 row)."'
          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