---
title: "create_map"
description: "Preview a shareable map for a known shortlist"
status: "preview"
canonical_url: "https://fairwayrent.ai/docs/agents/tools/create_map"
last_updated: "2026-11-09"
related:
  - "/docs/agents/tools"
audience: "agents, developers"
---

> For AI agents: This is a preview contract. The MCP endpoint is coming soon.

# create_map

Pass known listing IDs and optional landmarks to receive a shareable map URL. This tool is not callable yet.

## Purpose

Put a shortlist of known listing IDs on a shareable map with optional landmarks.

## When to use / when not to use

Use to share a shortlist of known listing IDs on one map. Do not use it to discover new listings. Unknown IDs are left out. If no ID is found, the call fails. Landmark names go into map_url as given, and the response landmarks array is empty for now. The /map page looks the names up when someone views it.

## Access

Preview: contract may change. Planned open access without an API key. The endpoint is coming soon.

## Annotations

`readOnlyHint: true`, `openWorldHint: false` (preview).

## Example request

Illustrative preview only. This is not a callable endpoint.

```json example

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "create_map",
    "arguments": {
      "listing_ids": [
        "listing-id"
      ],
      "landmarks": [
        "Menlo Park Caltrain"
      ]
    }
  }
}

```

## Example response

Illustrative shape only. Listing IDs, values, and URLs below are examples.

```json example

{
  "map_url": "https://www.fairwayrent.ai/map?l=listing-id",
  "pins": [
    {
      "listing_id": "listing-id",
      "lat": 37.45,
      "lng": -122.18
    }
  ],
  "landmarks": []
}

```

## Input schema

| Field | Type | Notes |
| --- | --- | --- |
| `listing_ids` | array | See JSON Schema |
| `landmarks` | array | See JSON Schema |

```json example

{
  "type": "object",
  "properties": {
    "listing_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "minItems": 1,
      "maxItems": 25
    },
    "landmarks": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 120,
        "minLength": 1
      },
      "maxItems": 10
    }
  },
  "required": [
    "listing_ids"
  ],
  "additionalProperties": false
}

```

## Output schema

| Field | Type | Notes |
| --- | --- | --- |
| `map_url` | string | See JSON Schema |
| `pins` | array | See JSON Schema |
| `landmarks` | array | See JSON Schema |

```json example

{
  "type": "object",
  "properties": {
    "map_url": {
      "type": "string",
      "format": "uri"
    },
    "pins": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "listing_id": {
            "type": "string"
          },
          "lat": {
            "type": "number"
          },
          "lng": {
            "type": "number"
          }
        },
        "required": [
          "listing_id",
          "lat",
          "lng"
        ]
      }
    },
    "landmarks": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "lat": {
            "type": "number"
          },
          "lng": {
            "type": "number"
          }
        },
        "required": [
          "name",
          "lat",
          "lng"
        ]
      }
    }
  },
  "required": [
    "map_url",
    "pins",
    "landmarks"
  ]
}

```

## Errors

These codes come from the MCP service in development. They can change before launch.

A request error is a tool result with `isError: true`. Its `structuredContent` has the HTTP `status`, a `code`, and the `path` of the field at fault. The same JSON is also the text content of the result.

```json example

{
  "status": 400,
  "code": "UNKNOWN_FIELD",
  "path": "filters.radius"
}

```

| Code | Path | Meaning |

| --- | --- | --- |

| `UNKNOWN_FIELD` | The unknown field | The request has a field that the schema does not list. Remove it. |

| `MALFORMED_REQUEST` | The invalid field | A field has the wrong type or is out of range. Fix the value. |

| `NO_LISTINGS_FOUND` | `listing_ids` | None of the listing IDs is a known listing with a location. |

If the service times out or cannot read its data, the result has `isError: true` and `{ "error": ... }` with `map_timeout` or `map_unavailable`. Retry later with the same request.

Rate limits and API key problems are not tool results. They are JSON-RPC errors. `error.data.error` names the problem, and `error.code` is the number below for that name. A rate-limit error also has `error.data.retry_after` in seconds and a `Retry-After` header. Wait that long before you retry.

```json example

{
  "rate_limited": -31001,
  "invalid_api_key": -31002,
  "insufficient_scope": -31003
}

```

## Notes for agents

Check `checked_at` before describing availability. Link to the Fairway listing. Keep renter preferences and ranking in your own context.
