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.

Operation	Credits	Per-minute limit	Result bound
List municipalities	1	60	Up to 250 summaries per page; names and codes only
Current municipality	1	60	One municipality
District summary	3	20	One municipality required
Annual history	5	12	Up to 10 annual rows, one property type
Compare	5	12	2–5 municipalities, up to 5 metrics
Search	10	6	Up to 20 rows, no pagination
Recipe catalog	1	60	Fixed versioned catalog
Recipe build	1	60	Validates one configuration; runs no query
Usage	1	60	Your own usage counters
MCP metadata	1	60	`initialize`/`tools/list` and similar control calls

Customer limits

Limit	Value
Monthly credits	10,000 credits per UTC calendar month
Global request rate	60 accepted operations per minute, across all your keys
Distinct municipalities	300 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.

Response headers

Every successful authenticated response includes:

Header	Meaning
`X-JLA-Credit-Cost`	Credits charged for this request
`X-JLA-Credits-Used`	Credits used so far this UTC calendar month
`X-JLA-Credits-Limit`	Monthly credit allowance (10,000)
`X-JLA-Municipalities-Used`	Distinct municipalities queried in the current rolling 30-day window
`X-JLA-Municipalities-Limit`	Rolling 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.

Parameter	Type	Required	Notes
`limit`	query, integer	No	1–250; default 100
`offset`	query, integer	No	0 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.

Parameter	Type	Required	Notes
`code`	path, string	Yes	Exactly 5 digits
`as_of`	query, string	No	ISO-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.

Parameter	Type	Required	Notes
`code`	path, string	Yes	Exactly 5 digits
`from_year`	query, integer	No	4 digits; default 2016
`to_year`	query, integer	No	4 digits, ≥ `from_year`; default 2025
`limit`	query, integer	No	1–10; default 10
`offset`	query, integer	No	0–10000; default 0
`property_type`	query, string	No	One 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.

Parameter	Type	Required	Notes
`city`	query, string	Yes	Exactly 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.

Field	Type	Required	Notes
`recipe_id`	string	Yes	One catalog ID, e.g. `R01`
`operation`	string	Yes	`detail`, `history`, `compare` or `search`; must be one the recipe supports
`city_codes`	array of string	Depends on operation	Exactly 1 for `detail`/`history`; 2–5 for `compare`; none for `search`
`property_type`	string	No	Must be one the recipe supports; defaults to the recipe's first
`from_year`, `to_year`	integer	No	2016–2025; default the full range
`order`	string	No	`asc` or `desc`; default `desc`
`limit`	integer	No	1–20; default 10; used only for `search`
`query`	string	No	1–80 characters; `search` only
`metric`	string	No	Must be one the recipe supports
`prefecture_code`	string	Depends	2 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.

Field	Type	Required	Notes
`query`	string	No	1–80 characters; matched against name and code
`prefecture_code`	string	Depends	2 digits; required unless `metric` is `transaction_count`
`property_type`	string	No	One of 3 property types; default `Pre-owned Condominiums, etc.`
`metric`	string	No	See metric list below; default `price_per_sqm_jpy`
`order`	string	No	`asc` or `desc`; default `desc`
`min_sample_count`	integer	No	1–1,000,000
`min_value`, `max_value`	number	No	Any finite number; `min_value` ≤ `max_value`
`limit`	integer	No	1–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.

Field	Type	Required	Notes
`city_codes`	array of string	Yes	2–5 unique 5-digit codes
`property_type`	string	No	One of 3 property types; default `Pre-owned Condominiums, etc.`
`metrics`	array of string	No	1–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.

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

Tool	Arguments	Cost
`get_city_stats`	`city_code` (required), `as_of`	1 credit
`search_districts`	`city_code` (required), `name`	3 credits
`get_price_history`	`city_code` (required), `from_year`, `to_year`, `limit` (max 10), `offset`, `property_type`	5 credits
`search_cities`	`query`, `prefecture_code`, `property_type`, `metric`, `order`, `min_sample_count`, `min_value`, `max_value`, `limit` (max 20)	10 credits
`compare_cities`	`city_codes` (required, 2–5), `property_type`, `metrics` (max 5)	5 credits
`get_usage`	none	1 credit
`list_recipes`	none	1 credit
`build_recipe`	`recipe_id` (required), `operation` (required), `city_codes`, `property_type`, `from_year`, `to_year`, `order`, `limit`, `query`, `metric`, `prefecture_code`	1 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 code	HTTP status	Meaning
`-32700`	200	The request body was not valid JSON
`-32600`	200	Not a valid JSON-RPC 2.0 request
`-32601`	200	Unknown JSON-RPC method
`-32602`	200	Invalid or unknown tool, or invalid arguments
`-32002`	200	The requested recipe is in preparation and not available yet (`data.code: "recipe_unavailable"`)
`-32001`	413	Request exceeds the 16 KB MCP request limit
`-32003`	200	The search index is temporarily unavailable
`-32603`	500	The 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.

ID	Name	What it answers	Operations	Notes
`R01`	Property price per m² finder	What is the typical price per square metre for a property type in a municipality?	detail, history, compare, search	Search needs one prefecture; medians shown only with 5+ records
`R02`	Property price year-on-year	How did the median price change from the prior year?	detail, history, compare, search	Both years need 5+ records; search needs one prefecture
`R03`	Three- and five-year price trend	Is the recent direction a persistent multi-year trend?	detail, history, compare, search	Every required year needs 5+ records; search needs one prefecture
`R04`	Ten-year peak position	How does today's price compare with its own ten-year high?	detail, history, compare, search	Historical comparison only, not a forecast; search needs one prefecture
`R05`	Land-and-building budget finder	Which municipalities fit a land-and-building total-price range?	detail, history, compare, search	Land-and-building property type only; search needs one prefecture
`R06`	Urban condominium pulse	What is the price level and recent history for pre-owned condominiums?	detail, history, compare, search	Condominiums only; search needs one prefecture
`R07`	Building-age price curve	How does price differ by condominium building-age band?	detail, history	Fixed 0–10/11–20/21–30/31+ year bands; not available in search or compare
`R08`	Renovation cohort observation	How do renovated and not-yet-renovated condominium medians differ?	detail, history, compare	Not available in search; an observed difference, not a causal effect
`R09`	Ten-year evidence continuity	Does this municipality have enough transaction evidence across ten years?	detail, history, compare, search	Evidence context, not popularity or demand
`R10`	Transaction-record composition	How many records exist, by property type and year?	detail, history, compare, search	Record counts only, not market activity
`G01`	Official land price in preparation	What is the official appraised land price for this area?	detail, history	Not returned by the API yet; land only
`G02`	Official land-price year-on-year in preparation	How did the official land price change from the prior year?	detail, history	Not returned by the API yet; land only
`G03`	Transaction-to-official comparison in preparation	How does the transaction price compare with the official land price?	detail, history	Not 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": "..." } }.

Code	HTTP status	Meaning	What to do
`missing_api_key`	401	No API key was supplied	Add an `Authorization: Bearer` header
`invalid_api_key`	401	The key is not recognized or was revoked	Check the key you're sending
`inactive_subscription`	403	The subscription behind this key is not active	Check your billing status
`rate_limit_exceeded`	429	The global 60/minute limit was reached	Wait the number of seconds given in the `Retry-After` header, then retry
`operation_rate_limit_exceeded`	429	The per-minute limit for this specific operation was reached	Wait the number of seconds given in the `Retry-After` header, then retry
`monthly_credit_quota_exceeded`	429	The 10,000-credit monthly allowance is used up	Wait for the reset at the start of the next UTC month; there is no overage
`unique_municipality_limit_exceeded`	429	The rolling 30-day 300-municipality limit was reached	Wait for older lookups to roll off, or query fewer distinct municipalities
`access_unavailable`	503	Access control is temporarily unavailable	Retry later
`runtime_configuration_unavailable`	503	The data service's configuration is temporarily unavailable	Retry later
`invalid_city_code`	400	The city code is not exactly 5 digits	Fix the code format
`city_not_found`	404	No data exists for that city code	Check the code with `GET /v1/cities`
`invalid_as_of`	400	`as_of` is not an ISO-8601 timestamp with a UTC offset	Use a format like `2025-01-01T00:00:00Z`
`snapshot_not_found`	404	No snapshot exists at or before the given `as_of`	Choose a later `as_of`, or omit it
`invalid_city_list_query`	400	`limit`/`offset` are invalid, or an unknown parameter was sent	Use only `limit` and `offset` within their allowed ranges
`invalid_history_query`	400	A history query parameter is invalid	Check `from_year`, `to_year`, `limit`, `offset` and `property_type`
`invalid_search`	400	The search request body is invalid	Check field names, types and bounds against this reference
`invalid_compare`	400	The comparison request body is invalid	Check `city_codes` and `metrics`
`invalid_recipe`	400	The recipe build request is invalid	Check `recipe_id`, `operation` and the other fields against the catalog
`recipe_unavailable`	409	The recipe's data (currently `G01`–`G03`) is not part of the data being served yet	Wait until official land prices ship; check `release_policy.official_land_price_pack.status` on `GET /v1/recipes`
`search_unavailable`	503	The search index is temporarily unavailable	Retry later
`unsupported_media_type`	415	The `Content-Type` header was not `application/json`	Set the header correctly
`request_too_large`	413	The request body exceeds 16 KB	Reduce the payload
`response_too_large` / `history_response_too_large`	500	The response would exceed the response-size limit	Request a narrower range or fewer fields
`invalid_path`	400	The request path contains percent-encoded characters	Use plain characters in the path; percent-encoding is only allowed in the query string
`route_not_found`	404	No route matches this path and method	Check the path and HTTP method
`internal_error`	500	An unexpected server error occurred	Retry 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:

Code	Meaning
`no_transactions`	There were no matching transaction records at all
`no_official_points`	There were no matching official land-price points
`below_sample_threshold`	Matching records exist, but fewer than the minimum of 5
`source_field_empty`	The source field needed for this value was empty in every matching record
`ambiguous_source_value`	Matching records existed, but the needed value was an ambiguous placeholder (for example an area recorded as 9999) and was excluded
`incomplete_period`	One or more years required for this time-based figure has no data, so it cannot be calculated
`unparsable_source_value`	The source value could not be read in the expected format
`out_of_range_source_value`	The source value had the right format but fell outside the allowed range
`not_applicable`	This 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.

1. Before you start

Base URL

Authentication

Response format

Attribution requirement

2. Credits and limits

Customer limits

Response headers

3. REST endpoints

GET/v1/health no key required · free

GET/v1/cities 1 credit

GET/v1/cities/{code} 1 credit

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

GET/v1/districts 3 credits

GET/v1/recipes 1 credit

POST/v1/recipes/build 1 credit

POST/v1/search 10 credits

POST/v1/compare 5 credits

GET/v1/usage 1 credit

4. MCP

Tools

Errors inside MCP

Generic MCP client configuration

5. Recipes

6. Errors

7. Data notes

Coverage

Sample-size rule

Missing-value reasons

8. Get an update when access opens

GET`/v1/health` no key required · free

GET`/v1/cities` 1 credit

GET`/v1/cities/{code}` 1 credit

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

GET`/v1/districts` 3 credits

GET`/v1/recipes` 1 credit

POST`/v1/recipes/build` 1 credit

POST`/v1/search` 10 credits

POST`/v1/compare` 5 credits

GET`/v1/usage` 1 credit