Japan Location API API reference · checkout is not open yet

API reference

Japan Location API returns municipality-level property prices and population data for Japan, joined on one municipality code, through a REST API and an MCP endpoint. Official land prices are in preparation. This page documents every route, parameter, credit cost and error code.

This is a developer reference. For a plain-language overview of what the service does, see the overview page; try it with sample data on the interactive preview.

1. Before you start

Base URL

API keys are issued once you complete self-service checkout, and checkout is not open yet. Requests in this reference use the placeholder $JLA_BASE_URL. The base URL is shown together with your key once access opens.

Authentication

Every route except GET /v1/health requires an API key in the Authorization header: 

Authorization: Bearer <your-api-key>

Response format

Every response is JSON. A successful response has the shape { "data": ..., "meta": { ... } }. An error response has the shape { "error": { "code": "...", "message": "..." } } and a matching HTTP status code (see Errors). Responses are private and are never cached (Cache-Control: private, no-store).

Attribution requirement

Every response's meta includes attribution_ja, disclaimer_ja, disclaimer_en and source_credits_ja. When you display returned data to a user, you must preserve this attribution and these disclaimers rather than showing only the numeric values. Returned figures are derived statistics, not official government publications, and are not a forecast or an appraisal.

2. Credits and limits

A request is billed in credits for its matching operation, and counted against that operation's per-minute limit, only once it begins processing; limits are aggregated across all of your API keys. A request rejected before processing — invalid input, an unknown route or method, a municipality code that does not exist, or a rate or quota-limit denial — is never billed. A request that is charged and then fails once processing has started — for example a storage error, a response too large to return, or an as_of date before any snapshot was captured — is automatically refunded: the credit is returned to that month, any reserved municipality slot is released, and the response shows X-JLA-Credit-Cost: 0 with the updated usage totals. Per-minute rate counters are not refunded, because that request's work already ran. On the rare occasion a refund cannot be recorded, the original charge stands and the credit headers are left off that response.

OperationCreditsPer-minute limitResult bound
List municipalities160Up to 250 summaries per page; names and codes only
Current municipality160One municipality
District summary320One municipality required
Annual history512Up to 10 annual rows, one property type
Compare5122–5 municipalities, up to 5 metrics
Search106Up to 20 rows, no pagination
Recipe catalog160Fixed versioned catalog
Recipe build160Validates one configuration; runs no query
Usage160Your own usage counters
MCP metadata160initialize/tools/list and similar control calls

Customer limits

LimitValue
Monthly credits10,000 credits per UTC calendar month
Global request rate60 accepted operations per minute, across all your keys
Distinct municipalities300 unique municipality codes in any rolling 30-day window

Requests rejected for a rate or quota reason do not use credits and do not count toward the municipality limit. When your monthly credit allowance is used up, requests return 429 until the allowance resets at the start of the next UTC calendar month. There is no overage charge — the plan is a single fixed monthly price. These limits are shared by every subscription and API key registered under the same billing email, so a second subscription under that email does not add capacity.

Response headers

Every /v1/* and /mcp response, success or error, includes X-JLA-Request-Id. A successful authenticated response also includes:

HeaderMeaning
X-JLA-Request-IdUnique ID for this request (present on every response, including errors) — quote it when contacting support
X-JLA-Credit-CostCredits charged for this request; 0 if it was later refunded
X-JLA-Credits-UsedCredits used so far this UTC calendar month
X-JLA-Credits-LimitMonthly credit allowance (10,000)
X-JLA-Municipalities-UsedDistinct municipalities queried in the current rolling 30-day window
X-JLA-Municipalities-LimitRolling 30-day municipality allowance (300)

3. REST endpoints

All REST routes are under /v1 and return JSON.

GET/v1/health no key required · free

A public uptime check. It does not use a credit and is not billed as an operation.

curl $JLA_BASE_URL/v1/health

Example values are fictional.

{
  "data": {
    "status": "ok",
    "schema_version": "0.16",
    "fixture_derived": false
  }
}

GET/v1/cities 1 credit

Lists municipality codes and names, in city-code order.

ParameterTypeRequiredNotes
limitquery, integerNo1–250; default 100
offsetquery, integerNo0 or more; default 0
 
curl "$JLA_BASE_URL/v1/cities?limit=2" \
  -H "Authorization: Bearer $JLA_API_KEY"

Example values are fictional.

{
  "data": [
    { "city_code": "13101", "city_name_en": "Chiyoda", "city_name_ja": "千代田区" },
    { "city_code": "13102", "city_name_en": "Chuo", "city_name_ja": "中央区" }
  ],
  "meta": {
    "pagination": {
      "limit": 2, "offset": 0, "returned": 2, "total": 1892, "next_offset": 2
    }
  }
}

GET/v1/cities/{code} 1 credit

Returns the current record for one municipality, or the most recent snapshot at or before a given time.

ParameterTypeRequiredNotes
codepath, stringYesExactly 5 digits
as_ofquery, stringNoISO-8601 timestamp with a UTC offset, e.g. 2025-06-01T00:00:00Z
 
curl "$JLA_BASE_URL/v1/cities/13113" \
  -H "Authorization: Bearer $JLA_API_KEY"

Example values are fictional. Abbreviated to one transaction type; a real response can carry several.

{
  "data": {
    "city_code": "13113",
    "city_name_en": "Shibuya",
    "city_name_ja": "渋谷区",
    "year": 2025,
    "transactions": {
      "count": 12, "count_with_area": 12, "excluded_ambiguous_area_count": 0,
      "by_type": [{
        "type": "Pre-owned Condominiums, etc.", "count": 12,
        "price_per_sqm": { "basis": "derived_trade_price_per_exclusive_area", "count": 12, "median_jpy": 950000, "excluded_ambiguous_count": 0 },
        "price_yoy": { "value_pct": 4.2, "current_year": 2025, "previous_year": 2024, "current_price_count": 12, "previous_price_count": 11, "min_sample_size": 5 },
        "price_cagr_3y": { "value_pct": 3.1, "current_year": 2025, "start_year": 2022, "elapsed_years": 3, "min_sample_size": 5,
          "annual_price_counts": [{"year": 2022, "transaction_count": 9, "price_count": 9, "excluded_ambiguous_count": 0}, {"year": 2023, "transaction_count": 10, "price_count": 10, "excluded_ambiguous_count": 0}, {"year": 2024, "transaction_count": 11, "price_count": 11, "excluded_ambiguous_count": 0}, {"year": 2025, "transaction_count": 12, "price_count": 12, "excluded_ambiguous_count": 0}] },
        "price_cagr_5y": { "value_pct": 2.6, "current_year": 2025, "start_year": 2020, "elapsed_years": 5, "min_sample_size": 5,
          "annual_price_counts": [{"year": 2020, "transaction_count": 8, "price_count": 8, "excluded_ambiguous_count": 0}, {"year": 2021, "transaction_count": 9, "price_count": 9, "excluded_ambiguous_count": 0}, {"year": 2022, "transaction_count": 9, "price_count": 9, "excluded_ambiguous_count": 0}, {"year": 2023, "transaction_count": 10, "price_count": 10, "excluded_ambiguous_count": 0}, {"year": 2024, "transaction_count": 11, "price_count": 11, "excluded_ambiguous_count": 0}, {"year": 2025, "transaction_count": 12, "price_count": 12, "excluded_ambiguous_count": 0}] },
        "price_vs_peak": { "value_pct": 0.0, "current_year": 2025, "window_start_year": 2016, "window_end_year": 2025, "calendar_year_count": 10, "peak_years": [2025], "is_current_peak": true, "min_sample_size": 5,
          "annual_price_counts": [{"year": 2016, "transaction_count": 6, "price_count": 6, "excluded_ambiguous_count": 0}, {"year": 2017, "transaction_count": 7, "price_count": 7, "excluded_ambiguous_count": 0}, {"year": 2018, "transaction_count": 7, "price_count": 7, "excluded_ambiguous_count": 0}, {"year": 2019, "transaction_count": 8, "price_count": 8, "excluded_ambiguous_count": 0}, {"year": 2020, "transaction_count": 8, "price_count": 8, "excluded_ambiguous_count": 0}, {"year": 2021, "transaction_count": 9, "price_count": 9, "excluded_ambiguous_count": 0}, {"year": 2022, "transaction_count": 9, "price_count": 9, "excluded_ambiguous_count": 0}, {"year": 2023, "transaction_count": 10, "price_count": 10, "excluded_ambiguous_count": 0}, {"year": 2024, "transaction_count": 11, "price_count": 11, "excluded_ambiguous_count": 0}, {"year": 2025, "transaction_count": 12, "price_count": 12, "excluded_ambiguous_count": 0}] }
      }],
      "pre_owned_condominium": {
        "count": 12, "building_year_valid_count": 12,
        "building_year_exclusions": { "source_field_empty_count": 0, "unparsable_source_value_count": 0, "out_of_range_source_value_count": 0 },
        "by_building_age_band": [
          { "building_age_band": "0-10", "count": 7, "price_per_sqm": { "basis": "derived_trade_price_per_exclusive_area", "count": 7, "median_jpy": 980000, "excluded_ambiguous_count": 0 } },
          { "building_age_band": "11-20", "count": 5, "price_per_sqm": { "basis": "derived_trade_price_per_exclusive_area", "count": 5, "median_jpy": 905000, "excluded_ambiguous_count": 0 } },
          { "building_age_band": "21-30", "count": 0, "price_per_sqm": { "basis": "derived_trade_price_per_exclusive_area", "count": 0, "median_jpy": null, "excluded_ambiguous_count": 0, "omitted_reason": "no_transactions" } },
          { "building_age_band": "31+", "count": 0, "price_per_sqm": { "basis": "derived_trade_price_per_exclusive_area", "count": 0, "median_jpy": null, "excluded_ambiguous_count": 0, "omitted_reason": "no_transactions" } }
        ],
        "renovation_observed_median_difference": {
          "basis": "derived_trade_price_per_exclusive_area", "value_pct": -4.5, "denominator_status": "Not yet",
          "groups": [
            { "renovation_status": "Done", "transaction_count": 6, "price_count": 6, "excluded_ambiguous_count": 0, "median_price_per_sqm_jpy": 935000 },
            { "renovation_status": "Not yet", "transaction_count": 6, "price_count": 6, "excluded_ambiguous_count": 0, "median_price_per_sqm_jpy": 979000 }
          ],
          "source_field_empty_count": 0, "min_sample_size_per_group": 5
        }
      }
    },
    "land_prices": {
      "count": 11, "count_with_price": 11, "median_price_per_sqm_jpy": 340000, "excluded_paused_count": 0, "year": 2025,
      "by_use_category": [
        { "use_category": "住宅地", "count": 6, "count_with_price": 6, "median_price_per_sqm_jpy": 298000,
          "official_land_price_yoy": { "basis": "source_year_on_year_change_rate", "observation_date": "2025-01-01", "median_pct": 6.4, "count": 6, "source_field_empty_count": 0, "min_sample_size": 5 } },
        { "use_category": "商業地", "count": 5, "count_with_price": 5, "median_price_per_sqm_jpy": 512000,
          "official_land_price_yoy": { "basis": "source_year_on_year_change_rate", "observation_date": "2025-01-01", "median_pct": 5.1, "count": 5, "source_field_empty_count": 0, "min_sample_size": 5 } }
      ],
      "by_land_price_type": [
        { "land_price_type": 0, "label": "koji", "valuation_date": "2025-01-01", "count": 11, "count_with_price": 11, "median_price_per_sqm_jpy": 340000,
          "by_use_category": [
            { "use_category": "住宅地", "count": 6, "count_with_price": 6, "median_price_per_sqm_jpy": 298000,
              "official_land_price_yoy": { "basis": "source_year_on_year_change_rate", "observation_date": "2025-01-01", "median_pct": 6.4, "count": 6, "source_field_empty_count": 0, "min_sample_size": 5 } },
            { "use_category": "商業地", "count": 5, "count_with_price": 5, "median_price_per_sqm_jpy": 512000,
              "official_land_price_yoy": { "basis": "source_year_on_year_change_rate", "observation_date": "2025-01-01", "median_pct": 5.1, "count": 5, "source_field_empty_count": 0, "min_sample_size": 5 } }
          ] },
        { "land_price_type": 1, "label": "prefectural_survey", "valuation_date": "2025-07-01", "count": 11, "count_with_price": 11, "median_price_per_sqm_jpy": 345000,
          "by_use_category": [
            { "use_category": "住宅地", "count": 6, "count_with_price": 6, "median_price_per_sqm_jpy": 305000,
              "official_land_price_yoy": { "basis": "source_year_on_year_change_rate", "observation_date": "2025-07-01", "median_pct": 5.8, "count": 6, "source_field_empty_count": 0, "min_sample_size": 5 } },
            { "use_category": "商業地", "count": 5, "count_with_price": 5, "median_price_per_sqm_jpy": 499000,
              "official_land_price_yoy": { "basis": "source_year_on_year_change_rate", "observation_date": "2025-07-01", "median_pct": 4.6, "count": 5, "source_field_empty_count": 0, "min_sample_size": 5 } }
          ] }
      ],
      "market_to_official_ratio": [
        { "land_price_type": 0, "label": "koji", "use_category": "住宅地", "basis": "annual_land_only_unit_price_median_to_official_point_price_median", "ratio": 1.05, "min_sample_size_per_group": 5,
          "transaction": { "region_group": "residential", "period": "2025-01-01/2025-12-31", "record_count": 6, "price_count": 6, "median_price_per_sqm_jpy": 313000 },
          "official": { "observation_date": "2025-01-01", "point_count": 6, "price_count": 6, "median_price_per_sqm_jpy": 298000 } },
        { "land_price_type": 0, "label": "koji", "use_category": "商業地", "basis": "annual_land_only_unit_price_median_to_official_point_price_median", "ratio": 0.94, "min_sample_size_per_group": 5,
          "transaction": { "region_group": "commercial", "period": "2025-01-01/2025-12-31", "record_count": 5, "price_count": 5, "median_price_per_sqm_jpy": 480000 },
          "official": { "observation_date": "2025-01-01", "point_count": 5, "price_count": 5, "median_price_per_sqm_jpy": 512000 } },
        { "land_price_type": 1, "label": "prefectural_survey", "use_category": "住宅地", "basis": "annual_land_only_unit_price_median_to_official_point_price_median", "ratio": 1.03, "min_sample_size_per_group": 5,
          "transaction": { "region_group": "residential", "period": "2025-01-01/2025-12-31", "record_count": 6, "price_count": 6, "median_price_per_sqm_jpy": 313000 },
          "official": { "observation_date": "2025-07-01", "point_count": 6, "price_count": 6, "median_price_per_sqm_jpy": 305000 } },
        { "land_price_type": 1, "label": "prefectural_survey", "use_category": "商業地", "basis": "annual_land_only_unit_price_median_to_official_point_price_median", "ratio": 0.96, "min_sample_size_per_group": 5,
          "transaction": { "region_group": "commercial", "period": "2025-01-01/2025-12-31", "record_count": 5, "price_count": 5, "median_price_per_sqm_jpy": 480000 },
          "official": { "observation_date": "2025-07-01", "point_count": 5, "price_count": 5, "median_price_per_sqm_jpy": 499000 } }
      ]
    }
  },
  "meta": { "snapshot": { "mode": "current" }, "schema_version": "0.16" }
}

With as_of, meta.snapshot.mode becomes capture_as_of and the response reflects the last snapshot captured at or before that time, not an observation-year record.

GET/v1/cities/{code}/history 5 credits

Returns annual observations for one municipality and one property type, at most 10 rows per call.

ParameterTypeRequiredNotes
codepath, stringYesExactly 5 digits
from_yearquery, integerNo4 digits; default 2016
to_yearquery, integerNo4 digits, ≥ from_year; default 2025
limitquery, integerNo1–10; default 10
offsetquery, integerNo0–10000; default 0
property_typequery, stringNoOne of the three property types below; default Pre-owned Condominiums, etc.

Property types: Pre-owned Condominiums, etc., Residential Land(Land Only), Residential Land(Land and Building).

curl "$JLA_BASE_URL/v1/cities/13113/history?from_year=2024&to_year=2025" \
  -H "Authorization: Bearer $JLA_API_KEY"

Example values are fictional.

{
  "data": [
    { "period": 2024, "statistics": { "transactions": { "by_type": [
      { "type": "Pre-owned Condominiums, etc.", "price_per_sqm": { "median_jpy": 910000, "count": 31 } }
    ] } } },
    { "period": 2025, "statistics": { "transactions": { "by_type": [
      { "type": "Pre-owned Condominiums, etc.", "price_per_sqm": { "median_jpy": 950000, "count": 38 } }
    ] } } }
  ],
  "meta": { "snapshot": {
    "selected_period": { "from_year": 2024, "to_year": 2025 },
    "property_type": "Pre-owned Condominiums, etc.",
    "pagination": { "limit": 10, "offset": 0, "returned": 2, "total": 2, "next_offset": null }
  } }
}

History is annual observation history (ordered by observation year), not a record of what the API returned on a past date. Use GET /v1/cities/{code}?as_of=... for that.

GET/v1/districts 3 credits

Lists the districts inside one municipality, with stable district identifiers.

ParameterTypeRequiredNotes
cityquery, stringYesExactly 5 digits
 
curl "$JLA_BASE_URL/v1/districts?city=13113" \
  -H "Authorization: Bearer $JLA_API_KEY"

Example values are fictional.

{
  "data": {
    "city_code": "13113",
    "districts": [
      {
        "district_name": "Ebisu",
        "stable_id": "13113-ebisu",
        "transaction_count": 12,
        "price_per_sqm": { "median_jpy": 1020000, "count": 10 }
      }
    ]
  }
}

GET/v1/recipes 1 credit

Returns the versioned catalog of recipes available for the data currently being served. Official land prices are in preparation, so G01–G03 are left out of this response until they ship; release_policy.official_land_price_pack.status reports in_preparation until then, and available once they do. See Recipes. 

curl "$JLA_BASE_URL/v1/recipes" \
  -H "Authorization: Bearer $JLA_API_KEY"

Example values are fictional.

{
  "data": {
    "schema_version": "allowlisted-recipe-builder-v1",
    "catalog_version": "recipe-catalog-2026-09-21-v1",
    "release_policy": { "official_land_price_pack": { "status": "in_preparation" } },
    "recipes": [
      { "id": "R01", "title_en": "Property price per m² finder", "availability": "limited_coverage" }
    ]
  },
  "meta": { "recipe_contract": { "arbitrary_sql": false, "raw_export": false } }
}

POST/v1/recipes/build 1 credit

Validates one recipe configuration and returns the equivalent REST and MCP call to run it. It does not run the query itself and does not use any municipality allowance.

FieldTypeRequiredNotes
recipe_idstringYesOne catalog ID, e.g. R01
operationstringYesdetail, history, compare or search; must be one the recipe supports
city_codesarray of stringDepends on operationExactly 1 for detail/history; 2–5 for compare; none for search
property_typestringNoMust be one the recipe supports; defaults to the recipe's first
from_year, to_yearintegerNo2016–2025; default the full range
orderstringNoasc or desc; default desc
limitintegerNo1–20; default 10; used only for search
querystringNo1–80 characters; search only
metricstringNoMust be one the recipe supports
prefecture_codestringDepends2 digits; required for search on price-based recipes; search only
 
curl "$JLA_BASE_URL/v1/recipes/build" \
  -H "Authorization: Bearer $JLA_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "recipe_id": "R01",
    "operation": "search",
    "prefecture_code": "13"
  }'

Example values are fictional.

{
  "data": {
    "schema_version": "allowlisted-recipe-builder-v1",
    "catalog_version": "recipe-catalog-2026-09-21-v1",
    "recipe": { "id": "R01", "title_en": "Property price per m² finder" },
    "input": {
      "operation": "search", "city_codes": [], "prefecture_code": "13",
      "property_type": "Pre-owned Condominiums, etc.", "metric": "price_per_sqm_jpy"
    },
    "execution": {
      "rest": { "method": "POST", "path": "/v1/search", "body": { "prefecture_code": "13" } },
      "mcp": { "tool": "search_cities", "arguments": { "prefecture_code": "13" } }
    }
  }
}

Building one of the three official-land-price recipes (G01–G03) while they are in preparation returns 409 recipe_unavailable instead (MCP: JSON-RPC error -32002), before any credit is charged.

POST/v1/search 10 credits

Searches across municipalities for one metric, returning at most 20 rows with no pagination.

FieldTypeRequiredNotes
querystringNo1–80 characters; matched against name and code
prefecture_codestringDepends2 digits; required unless metric is transaction_count
property_typestringNoOne of 3 property types; default Pre-owned Condominiums, etc.
metricstringNoSee metric list below; default price_per_sqm_jpy
orderstringNoasc or desc; default desc
min_sample_countintegerNo1–1,000,000
min_value, max_valuenumberNoAny finite number; min_value ≤ max_value
limitintegerNo1–20; default 10

Search metrics: transaction_count, price_per_sqm_jpy, total_price_median_jpy, price_yoy_pct, price_cagr_3y_pct, price_cagr_5y_pct, price_vs_peak_pct, population_total. Price-based metrics require one prefecture_code because national coverage for those metrics is still partial; transaction_count may be searched nationwide. Municipality codes returned by search count toward your rolling 30-day municipality limit. 

curl "$JLA_BASE_URL/v1/search" \
  -H "Authorization: Bearer $JLA_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "prefecture_code": "13",
    "metric": "total_price_median_jpy",
    "order": "asc",
    "max_value": 60000000,
    "min_sample_count": 20,
    "limit": 2
  }'

Example values are fictional.

{
  "data": { "results": [
    { "city_code": "13113", "city_name_en": "Shibuya", "year": 2025,
      "metric": "total_price_median_jpy", "value": 58000000, "sample_count": 24 },
    { "city_code": "13102", "city_name_en": "Chuo", "year": 2025,
      "metric": "total_price_median_jpy", "value": 59500000, "sample_count": 21 }
  ] },
  "meta": { "search": {
    "metric": "total_price_median_jpy", "order": "asc", "limit": 2, "returned": 2, "pagination": false
  } }
}

POST/v1/compare 5 credits

Compares 2–5 municipalities on the same property type using up to 5 metrics.

FieldTypeRequiredNotes
city_codesarray of stringYes2–5 unique 5-digit codes
property_typestringNoOne of 3 property types; default Pre-owned Condominiums, etc.
metricsarray of stringNo1–5 unique metrics; default price_per_sqm_jpy, price_yoy_pct, transaction_count

Compare accepts every search metric plus renovation_observed_difference_pct (not available in search because it is an unadjusted cohort observation, not a ranking). 

curl "$JLA_BASE_URL/v1/compare" \
  -H "Authorization: Bearer $JLA_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "city_codes": ["13101", "13102", "13103"],
    "metrics": ["price_per_sqm_jpy", "price_yoy_pct"]
  }'

Example values are fictional.

{
  "data": { "cities": [
    { "city_code": "13101", "city_name_en": "Chiyoda", "year": 2025,
      "metrics": {
        "price_per_sqm_jpy": { "value": 1120000, "sample_count": 14 },
        "price_yoy_pct": { "value": 2.4, "sample_count": 14 }
      } }
  ] },
  "meta": { "compare": { "metrics": ["price_per_sqm_jpy", "price_yoy_pct"], "municipality_count": 3, "maximum_municipalities": 5 } }
}

GET/v1/usage 1 credit

Returns your own current monthly credit and rolling municipality usage.

curl "$JLA_BASE_URL/v1/usage" \
  -H "Authorization: Bearer $JLA_API_KEY"

Example values are fictional.

{
  "data": {
    "plan_code": "self_service",
    "credits": { "used": 340, "limit": 10000, "reset": "UTC calendar month" },
    "municipalities": { "used": 12, "limit": 300, "window": "rolling 30 days" },
    "request_credit_cost": 1
  }
}

4. MCP

POST /mcp exposes the same operations to AI assistants through JSON-RPC 2.0, using initialize, tools/list and tools/call. REST and MCP charge the same credit cost for the same underlying operation. A notification (a call with no id), an unknown method, and tools/call with an invalid or unknown tool name are never billed; only initialize and tools/list cost 1 credit each. 

curl "$JLA_BASE_URL/mcp" \
  -H "Authorization: Bearer $JLA_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": { "name": "get_city_stats", "arguments": { "city_code": "13113" } }
  }'

Example values are fictional.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{ "type": "text", "text": "{\"data\":{\"city_code\":\"13113\", ... }}" }]
  }
}

A tool's result is returned as a JSON string inside result.content[0].text — parse that string to get the same data/meta shape as the matching REST response.

Tools

ToolArgumentsCost
get_city_statscity_code (required), as_of1 credit
search_districtscity_code (required), name3 credits
get_price_historycity_code (required), from_year, to_year, limit (max 10), offset, property_type5 credits
search_citiesquery, prefecture_code, property_type, metric, order, min_sample_count, min_value, max_value, limit (max 20)10 credits
compare_citiescity_codes (required, 2–5), property_type, metrics (max 5)5 credits
get_usagenone1 credit
list_recipesnone1 credit
build_reciperecipe_id (required), operation (required), city_codes, property_type, from_year, to_year, order, limit, query, metric, prefecture_code1 credit

search_districts requires city_code and filters districts inside that one municipality; name is an optional case-insensitive substring match.

Errors inside MCP

An authorization failure (missing or invalid key, or a quota/rate limit) returns the same { "error": { "code", "message" } } body and HTTP status as the REST API — not a JSON-RPC error. A protocol-level problem (malformed JSON-RPC, unknown method, invalid tool arguments) returns a JSON-RPC error object, almost always with HTTP status 200:

JSON-RPC codeHTTP statusMeaning
-32700200The request body was not valid JSON
-32600200Not a valid JSON-RPC 2.0 request
-32601200Unknown JSON-RPC method
-32602200Invalid or unknown tool, or invalid arguments
-32002200The requested recipe is in preparation and not available yet (data.code: "recipe_unavailable")
-32001413Request exceeds the 16 KB MCP request limit
-32003200The search index is temporarily unavailable
-32603500The response would exceed the size limit

Generic MCP client configuration

Point any MCP client that supports an HTTP transport at the endpoint with your key in the Authorization header:

{
  "mcpServers": {
    "japan-location-api": {
      "url": "$JLA_BASE_URL/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer $JLA_API_KEY"
      }
    }
  }
}

Field names vary between MCP clients; this shows the information every HTTP-transport client needs (URL, transport type and the Bearer header).

5. Recipes

A recipe is a named, pre-validated question. GET /v1/recipes (or MCP list_recipes) lists the catalog; POST /v1/recipes/build (or MCP build_recipe) checks your inputs against one recipe and returns the exact REST or MCP call to run — it never runs arbitrary SQL, code or formulas, and never returns a raw data export.

IDNameWhat it answersOperationsNotes
R01Property price per m² finderWhat is the typical price per square metre for a property type in a municipality?detail, history, compare, searchSearch needs one prefecture; medians shown only with 5+ records
R02Property price year-on-yearHow did the median price change from the prior year?detail, history, compare, searchBoth years need 5+ records; search needs one prefecture
R03Three- and five-year price trendIs the recent direction a persistent multi-year trend?detail, history, compare, searchEvery required year needs 5+ records; search needs one prefecture
R04Ten-year peak positionHow does today's price compare with its own ten-year high?detail, history, compare, searchHistorical comparison only, not a forecast; search needs one prefecture
R05Land-and-building budget finderWhich municipalities fit a land-and-building total-price range?detail, history, compare, searchLand-and-building property type only; search needs one prefecture
R06Urban condominium pulseWhat is the price level and recent history for pre-owned condominiums?detail, history, compare, searchCondominiums only; search needs one prefecture
R07Building-age price curveHow does price differ by condominium building-age band?detail, historyFixed 0–10/11–20/21–30/31+ year bands; not available in search or compare
R08Renovation cohort observationHow do renovated and not-yet-renovated condominium medians differ?detail, history, compareNot available in search; an observed difference, not a causal effect
R09Ten-year evidence continuityDoes this municipality have enough transaction evidence across ten years?detail, history, compare, searchEvidence context, not popularity or demand
R10Transaction-record compositionHow many records exist, by property type and year?detail, history, compare, searchRecord counts only, not market activity
G01Official land price in preparationWhat is the official appraised land price for this area?detail, historyNot returned by the API yet; land only
G02Official land-price year-on-year in preparationHow did the official land price change from the prior year?detail, historyNot returned by the API yet; land only
G03Transaction-to-official comparison in preparationHow does the transaction price compare with the official land price?detail, historyNot returned by the API yet; land only; not an under/overpricing signal

The three official-land-price recipes above are not returned by GET /v1/recipes or MCP list_recipes while the data currently being served has no official land-price source; release_policy.official_land_price_pack.status reports in_preparation and becomes available once that data ships. Building one of them with POST /v1/recipes/build or MCP build_recipe returns 409 recipe_unavailable (MCP: JSON-RPC error -32002) instead, and uses no credit.

6. Errors

An error response has the shape { "error": { "code": "...", "message": "..." } }.

CodeHTTP statusMeaningWhat to do
missing_api_key401No API key was suppliedAdd an Authorization: Bearer header
invalid_api_key401The key is not recognized or was revokedCheck the key you're sending
inactive_subscription403The subscription behind this key is not activeCheck your billing status
rate_limit_exceeded429The global 60/minute limit was reachedWait the number of seconds given in the Retry-After header, then retry
operation_rate_limit_exceeded429The per-minute limit for this specific operation was reachedWait the number of seconds given in the Retry-After header, then retry
monthly_credit_quota_exceeded429The 10,000-credit monthly allowance is used upWait for the reset at the start of the next UTC month; there is no overage
unique_municipality_limit_exceeded429The rolling 30-day 300-municipality limit was reachedWait for older lookups to roll off, or query fewer distinct municipalities
access_unavailable503Access control is temporarily unavailableRetry later
runtime_configuration_unavailable503The data service's configuration is temporarily unavailableRetry later
invalid_city_code400The city code is not exactly 5 digitsFix the code format
city_not_found404No data exists for that city codeCheck the code with GET /v1/cities
invalid_as_of400as_of is not an ISO-8601 timestamp with a UTC offsetUse a format like 2025-01-01T00:00:00Z
snapshot_not_found404No snapshot exists at or before the given as_ofChoose a later as_of, or omit it
invalid_city_list_query400limit/offset are invalid, or an unknown parameter was sentUse only limit and offset within their allowed ranges
invalid_history_query400A history query parameter is invalidCheck from_year, to_year, limit, offset and property_type
invalid_search400The search request body is invalidCheck field names, types and bounds against this reference
invalid_compare400The comparison request body is invalidCheck city_codes and metrics
invalid_recipe400The recipe build request is invalidCheck recipe_id, operation and the other fields against the catalog
recipe_unavailable409The recipe's data (currently G01–G03) is not part of the data being served yetWait until official land prices ship; check release_policy.official_land_price_pack.status on GET /v1/recipes
search_unavailable503The search index is temporarily unavailableRetry later
unsupported_media_type415The Content-Type header was not application/jsonSet the header correctly
request_too_large413The request body exceeds 16 KBReduce the payload
response_too_large / history_response_too_large500The response would exceed the response-size limitRequest a narrower range or fewer fields
invalid_path400The request path contains percent-encoded charactersUse plain characters in the path; percent-encoding is only allowed in the query string
route_not_found404No route matches this path and methodCheck the path and HTTP method
method_not_allowed405HEAD was used on a metered GET data route (the response carries an Allow: GET header). HEAD responses carry no body, so only the status and Allow header are visibleUse GET
internal_error500An unexpected server error occurredRetry later

7. Data notes

Coverage

1,892 municipalities with annual observations for 2016–2025. Property prices come from MLIT reported real-estate transaction records; municipality names and codes also come from MLIT; 2025 population and household counts come from Japan's Statistics Bureau via e-Stat. Municipality boundaries and district layouts are not geographic data — no map geometry is included.

Sample-size rule

A median or derived figure is only returned when at least 5 matching records exist. Below that threshold, the value is null and an omitted_reason explains why, alongside the actual count.

Missing-value reasons

Every omitted_reason code means:

CodeMeaning
no_transactionsThere were no matching transaction records at all
no_official_pointsThere were no matching official land-price points
below_sample_thresholdMatching records exist, but fewer than the minimum of 5
source_field_emptyThe source field needed for this value was empty in every matching record
ambiguous_source_valueMatching records existed, but the needed value was an ambiguous placeholder (for example an area recorded as 9999) and was excluded
incomplete_periodOne or more years required for this time-based figure has no data, so it cannot be calculated
unparsable_source_valueThe source value could not be read in the expected format
out_of_range_source_valueThe source value had the right format but fell outside the allowed range
not_applicableThis figure does not apply in this context (for example, a per-square-metre price for a combined land-and-building transaction that cannot be separated)

Returned figures are historical, observed statistics. They are not a forecast, a property appraisal, an investment return, or a complete nationwide ranking.

8. Get an update when access opens

Join the waitlist for a launch date update. You can also tell us the first question you would want the service to answer.

We will only use your email for updates about this service. Reply to any email from us to ask us to delete it.