Known Limitations

1. Category gaps in the source data

Measured as of 2026-10-13: 296,412 of 2,629,417 records (11.3%) carry category unknown in the upstream corpus.

Effect: the municipality census under-counts those records under every category, and the mixed-category breakdown in the catchment signal has an unknown bucket.

What we are doing: LLM re-categorization of the full unknown bucket into a 17-class taxonomy is in production and will remove the bucket from the census. Until then, treat unknown as unclassified, not as zero.

2. Coordinate drift

Some Overture-sourced records carry coordinates that drift from the true location. This is worst for tourist landmarks, large parks, and rail stations, where a single representative point may be placed hundreds of metres to a few kilometres from the actual entrance.

What we are doing: 2,629,417 facility records are aggregated by prefecture and 16 categories; records without a prefecture label are assigned by coordinates data. The jp_poi_quality signal scores each record 0-100 from coordinate plausibility, address completeness, and category resolution (mean 84.9). Filter on it rather than trusting every coordinate equally.

3. Closed facilities persist until the next rebuild

Upstream has no closure feed. A closed shop stays in the data until its municipality removes it from the next weekly publication.

What we are doing: the jp_poi_aliveness index estimates open/closed probability 0-100 from source recency, category stability, and temporal signals. It is an estimate, not a fact. Use min_score to prioritise likely-open records, and verify business-critical decisions against the operator's own channels.

4. Coverage is not exhaustive

The corpus covers food-service and retail facilities published by municipalities plus Overture Maps Places. It is not a complete census of Japanese businesses. Small sole traders, newly opened shops (added weekly at best), and sectors without a municipal permit requirement are under-represented.

5. Upstream rebuild cadence

• Municipal food facility data (81 sources): rebuilt weekly, Monday 04:00 JST.
• Overture Maps Places: pinned to release 2026-08-19.0.
• Railway station data (9,046 stations, MLIT National Land Numeric Information): refreshed on MLIT release.

Derived signals are regenerated daily from our own snapshot, so freshness is at least upstream freshness, never less. Every response carries computed_at and algorithm_version, so you can always tell how current a dataset is.

6. Search is not the product

Raw name/address search is available upstream for free. We sell derived aggregates: the census, the catchment, the chain index, and the aliveness index. Do not use this API where raw search would do. It is the wrong tool and the pricing reflects the aggregation, not the raw lookups.

What is not limited

• Storage and caching are permitted, including for commercial use. Redistribution and modification are also permitted under CC BY 4.0 with attribution. Keep the per-record licenses and attributions arrays when you store records.
• No rate-limit surprise: limits are published per tier and returned in response headers on every call.
• No billing surprise: paid signals state the exact amount in the 402 response before you pay anything.

Resolve an issue yourself

Support is documentation-first and fully self-service; there is no human support. The OpenAPI specification at /api/v1/openapi is the contract: it lists every path, parameter, response code and plan entitlement. Every error response carries a machine-readable reason and the next step, so a failed call tells you what to change without anyone replying to you. The machine-readable reference is at /jp-places/llms.txt, and the terms (including the support policy and the refund rules per billing path) are in the Terms of Service.

Paid endpoints are billed either through a RapidAPI subscription (refundable via RapidAPI support, which handles those payments as the merchant of record) or per call over x402 (settled on-chain and therefore final). A request that does not complete is not charged in the first place.