External API reference

All endpoints are HTTPS JSON APIs. Send request bodies with Content-Type: application/json. Errors are returned in a common format (error.code / error.message).

Base URL

https://realestate-api-297361533323.asia-northeast1.run.app/api/v1

Only the export endpoints (/export/*) return a file (binary) on success.

Send the API key (a string starting with mkr_api_) issued on My page → "Account settings" tab → "External API (for developers)" in the Authorization header using the Bearer scheme.

Authorization: Bearer mkr_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• The API key is shown only once when issued. If you lose it, issue a new one (the old key stops working immediately).
• If you set "Allowed IP addresses", requests from other IPs / CIDRs get 403 (IP_NOT_ALLOWED). You can check your source IP with clientIp in GET /me.
• Keep the API key on your servers; never embed it in browsers or apps. MCP keys (mkr_live_) cannot be used with this API.

Each API key owner can use up to 200 units per day. Each endpoint consumes the following units.

• Units reset every day at 00:00 UTC. Calls over the limit return HTTP 429 (DAILY_LIMIT_EXCEEDED) and are not executed.
• Bursts are limited to 20 calls per minute per API key (HTTP 429 RATE_LIMITED with Retry-After: 60).
• In addition, the whole service is protected by a limit of 100 requests per 15 minutes per source IP.
• If house plan generation fails (GENERATION_FAILED), the consumed units are refunded.

Usage is reported in the response headers.

X-RateLimit-Limit: 200
X-RateLimit-Remaining: 180
X-RateLimit-Reset: 1790640000        # Unix time (next 00:00 UTC)
Retry-After: 43200                   # only on 429

GET/api/v1/me

Returns whether the API key is valid, your current source IP, the allowed IPs and today's usage. Consumes no units.

curl https://realestate-api-297361533323.asia-northeast1.run.app/api/v1/me \
  -H "Authorization: Bearer $MEKIKI_API_KEY"

{
  "plan": "pro",
  "clientIp": "203.0.113.10",
  "allowedIps": ["203.0.113.10", "198.51.100.0/24"],
  "usage": { "used": 20, "limit": 200, "remaining": 180, "resetAt": "2026-09-30T00:00:00.000Z" },
  "costs": { "generateHouse": 20, "exterior": 10, "export": 2 }
}

POST/api/v1/generate-house

From an area and wishes, AI generates a house plan (JSON) with floor plans for every floor, a design concept, an estimated total budget and a simplified wall-quantity check.

curl -X POST https://realestate-api-297361533323.asia-northeast1.run.app/api/v1/generate-house \
  -H "Authorization: Bearer $MEKIKI_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 600 \
  -d '{
    "prefecture": "東京都",
    "municipality": "江戸川区",
    "tags": ["駐車場1台", "3階建て"],
    "includeExterior": false,
    "termsAccepted": true
  }'

{
  "requestId": "3f1c2a9e-7b1d-4c3e-9a51-6f0d2c8e4b77",
  "planSource": "ai",
  "plan": {
    "site": { "area": 80, "streetSide": "south" },
    "building": { "width": 5.46, "depth": 7.28, "floors": 3, "parkingSpaces": 1 },
    "roof": { "type": "flat", "eavesDepth": 0 },
    "floors": [
      {
        "level": 1,
        "rooms": [{ "type": "garage", "x": 0, "y": 0, "width": 2.73, "height": 5.46, "label": "ガレージ" }, "..."],
        "doors": ["..."], "openings": ["..."], "furnitures": ["..."]
      },
      "..."
    ],
    "externalStructures": ["..."]
  },
  "conceptExplanation": "想定総予算：約6,970万円（土地 …）…",
  "budget": { "landCost": 35200000, "buildingCost": 34779000, "total": 69979000, "...": "..." },
  "structuralWarning": ["1階のX方向（間口方向）の壁量が不足しています（存在壁量 14.43m / 必要壁量 18.29m）"],
  "structuralCheck": { "method": "simplified_wall_quantity", "floors": ["..."] }
}

• Generation takes about 1–3 minutes (about 30 seconds more with the exterior). Set your client timeout to around 10 minutes.
• Coordinates and dimensions are in metres and aligned to the 910mm module (multiples of 0.91m). The origin is the front-left corner of the building as seen from the road.
• With includeExterior: true the response also contains exterior (imageBase64, mimeType).
• Generated plans are also saved to your generation history on My page (requestId is the history ID).

POST/api/v1/export/pptx

POST/api/v1/export/dxf

Send the plan returned by generate-house to get an editable PowerPoint (.pptx) or a CAD-ready DXF (.dxf).

# 1) Generate a plan and keep only { plan, location }
curl -s -X POST https://realestate-api-297361533323.asia-northeast1.run.app/api/v1/generate-house \
  -H "Authorization: Bearer $MEKIKI_API_KEY" -H "Content-Type: application/json" \
  -d '{"prefecture":"東京都","municipality":"江戸川区","termsAccepted":true}' \
  | jq '{plan: .plan, location: "東京都江戸川区"}' > plan.json

# 2) Export it as DXF (or /export/pptx)
curl -X POST https://realestate-api-297361533323.asia-northeast1.run.app/api/v1/export/dxf \
  -H "Authorization: Bearer $MEKIKI_API_KEY" -H "Content-Type: application/json" \
  --data @plan.json -o floor-plan.dxf

• PPTX: one slide per floor; rooms, furniture and doors are individual shapes, with your company name, contact and the disclaimer in the footer.
• DXF: R12, millimetres, Japanese text in Shift_JIS. Walls, grid lines, doors, room names and dimensions are on separate layers, with your company name and the disclaimer in the title block.
• Company name and contact come from your white-label settings on My page (Mekiki Research credits if not set).

GET/api/v1/signals/{cityCode}

Returns, for a 5-digit municipality code, the leading-signal gap index per town (score, rank S–C), the area regime, and the municipality's redevelopment / subsidy / hazard information — each with source URL, verification date and disclaimer.

curl "https://realestate-api-297361533323.asia-northeast1.run.app/api/v1/signals/13122?wait=25" \
  -H "Authorization: Bearer $MEKIKI_API_KEY"

{
  "cityCode": "13122",
  "municipalityName": "葛飾区",
  "towns": [
    {
      "townName": "新小岩",
      "momentumDeviation": 21.2, "rank": "C", "gapZScore": -2.88,
      "zPop": -0.94, "zPrice": 1.94, "reliability": "normal",
      "regime": "REDEVELOPMENT_DRIVEN",
      "linkedIntel": [{ "category": "REDEVELOPMENT", "title": "新小岩駅南口地区第一種市街地再開発事業",
        "sourceUrl": "https://www.city.katsushika.lg.jp/...", "verifiedAt": "2026-10-18T05:06:09.013Z", "match": "direct" }],
      "sources": [{ "source_url": "https://www.e-stat.go.jp/dbview?sid=8003006792", "source_title": "...", "verified_at": "..." }]
    }
  ],
  "intel": { "status": "ready", "origin": "registered", "items": [{ "category": "SUBSIDY", "sourceUrl": "https://...", "verifiedAt": "..." }] },
  "disclaimer": "...",
  "cache": { "status": "persistent", "cachedAt": "...", "expiresAt": "..." }
}

• The town ranking (gap index) returns within seconds. If the municipal information (intel) is not ready yet, intel.status is "pending": call again with ?wait=25 (waits up to 25 s) until it becomes "ready". Results are cached for 7 days.
• This is a statistical comparison between towns and contains no property prices or future prices. Show the disclaimer and the sources when you display or redistribute it.
• Municipal information uses registered URLs where available; otherwise official websites (*.lg.jp / city.*.jp etc.) are searched automatically and only pages that return 200 and mention the municipality are used (intel.origin = discovered). If none are found, intel.status = "unavailable" (the gap index is still returned).

On errors the API returns the HTTP status and JSON in the following format.

{
  "error": {
    "code": "DAILY_LIMIT_EXCEEDED",
    "message": "Daily API limit reached (195/200 units; this call needs 20). Resets at 2026-09-30T00:00:00.000Z"
  }
}