fittings-geo

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

fittings-geo

Eleven services on

https://fittings.sh

that answer where something is. Every one that touches data fronts a US federal public-domain source — the Census Bureau geocoder and its TIGER street layers, the FCC block lookup, USGS 3DEP elevation — or the public-domain OurAirports dataset; one is pure arithmetic and touches nothing. Browsing and searching cost nothing. A call costs between $0.003 and $0.008 in this slice; nothing anywhere in the wider catalog exceeds $0.01.

Live list for this slice, free to read and free to search:

bash

curl -s "https://fittings.sh/catalog?category=Geography%20and%20places"
node scripts/call.mjs --search "address to census tract"
node scripts/call.mjs --describe census.geography-bundle

Service	Price	What it answers
`geo.forward-geocode`	$0.003	Where is this address, as a coordinate
`census.address-geographies`	$0.003	The same, plus the tract, county and block the address falls in
`addr.standardize`	$0.003	What is the canonical form of this messy address
`census.geocode-batch`	$0.004	The same for up to ten addresses in one request
`geo.reverse-geocode`	$0.003	What address, county and tract is this coordinate in
`fcc.census-block`	$0.003	The 15-digit block FIPS code containing this coordinate
`census.geography-bundle`	$0.008	Every Census layer through this coordinate, districts included
`road.nearest`	$0.004	Which street is this GPS fix on
`airport.nearby`	$0.003	Which airports are near this coordinate, and how far
`geo.elevation`	$0.003	How high is the ground here
`geo.distance`	$0.003	How far and in what direction between two coordinates

https://fittings.sh

上提供11项服务，用于查询地点相关信息。所有涉及数据的服务均基于美国联邦公共领域数据源——人口普查局地理编码器及其TIGER街道图层、FCC地块查询工具、USGS 3DEP海拔数据——或公共领域的OurAirports数据集；其中一项为纯算术运算，不涉及任何外部数据。浏览和搜索服务完全免费。该分类下的单次调用费用在0.003至0.008美元之间；整个服务目录中，任何服务的单次调用费用均不超过0.01美元。

该分类的实时服务列表，可免费查看和搜索：

bash

curl -s "https://fittings.sh/catalog?category=Geography%20and%20places"
node scripts/call.mjs --search "address to census tract"
node scripts/call.mjs --describe census.geography-bundle

服务	价格	功能说明
`geo.forward-geocode`	$0.003	将地址转换为坐标点
`census.address-geographies`	$0.003	同上，额外返回地址所属的人口普查区、县和地块信息
`addr.standardize`	$0.003	将混乱地址转换为标准格式
`census.geocode-batch`	$0.004	单次请求最多处理10个地址，功能同上
`geo.reverse-geocode`	$0.003	根据坐标点返回对应的地址、县和人口普查区信息
`fcc.census-block`	$0.003	返回坐标点所属的15位地块FIPS代码
`census.geography-bundle`	$0.008	返回坐标点对应的所有人口普查层级数据，包括选区信息
`road.nearest`	$0.004	查询GPS定位点所在的街道
`airport.nearby`	$0.003	查询坐标点附近的机场及距离
`geo.elevation`	$0.003	查询该点的地面海拔
`geo.distance`	$0.003	查询两个坐标点之间的距离和方位

When to reach for this

适用场景

The failure this exists to prevent is a fabricated location. A model asked for the coordinates of an address will produce a lat/lon of the right shape, in roughly the right city, and wrong by a few hundred metres or a few degrees; asked for a census tract it will produce eleven digits that parse, sort and join like a real GEOID and belong to somewhere else entirely. Neither is visible to a reader, neither is caught by a schema, and both survive every downstream step until someone drives to the wrong building or files a report about the wrong neighbourhood. So buy the lookup rather than recall it, every time the answer leaves your context.

Two jobs cover nearly all of it. Placing an address — which is geocoding, standardizing, or joining to a tract so the address can meet a public dataset. Placing a point — which is naming the address, the jurisdiction, the street or the terrain underneath a coordinate you were handed by a device, a photo or an earlier call. The rest are small spatial facts that are tedious to compute and easy to get quietly wrong: how far apart, which way, how high, which airport.

The tract is the one worth understanding, because it is why this slice earns its keep. A Census tract GEOID is the join key for almost every US public dataset — ACS demographics, HMDA lending, CDC health, EPA screening, most grant and eligibility rules — and the address-to-tract mapping lives in a TIGER shapefile, not in a model. Until an address has a tract, none of that data is reachable.

该服务旨在避免生成虚假位置信息。当模型被要求返回某地址的坐标时，会生成格式正确、大致位于目标城市的经纬度，但误差可能达到数百米甚至数度；当被要求返回人口普查区时，会生成符合格式的11位数字，看似真实的GEOID，但实际对应完全不同的区域。这些错误无法通过人工核验，也不会被模式校验捕获，会一直存在于下游流程中，直到有人导航到错误建筑或提交关于错误社区的报告。因此，每当答案超出你的上下文范围时，请选择调用该服务进行查询，而非自行生成。

该服务主要覆盖两类任务：地址定位——即地理编码、地址标准化，或关联到人口普查区以便对接公共数据集；坐标点定位——即根据设备、照片或前期调用获取的坐标，返回对应的地址、管辖区域、街道或地形信息。其余功能则用于处理繁琐且容易出错的小型空间信息计算：距离、方位、海拔、附近机场等。

人口普查区的作用尤为重要，也是该服务的核心价值所在。人口普查区GEOID是几乎所有美国公共数据集的关联键——包括ACS人口统计数据、HMDA贷款数据、CDC健康数据、EPA筛查数据，以及大多数拨款和资格规则——而地址到人口普查区的映射仅存在于TIGER shapefile中，而非模型权重里。只有获取到地址对应的人口普查区，才能访问这些公共数据集。

When not to use it

不适用场景

This is not a maps product. There is no routing, no drive time, no traffic, no turn-by-turn, no isochrone, no polygon geometry to draw, no tiles, no places search and no points of interest. It will not tell you what business is at an address, whether a building exists, or what a neighbourhood is like.

road.nearest

names the street a point sits on; it does not route along it.

It also does not go one hop past the data.

census.geography-bundle

names the congressional district containing a point and not the member who holds the seat — the bills that member filed are the civic slice,

/skill/fittings-civic

. Flood zone, weather grid and hazard layers for a point are the weather slice. And do not buy a lookup whose answer you already hold: an address the user supplied with its coordinates does not need geocoding unless the point of the call is to check that pairing.

这并非地图类产品，不提供路径规划、行驶时间、交通状况、逐向导航、等时线、可绘制的多边形几何图形、地图瓦片、地点搜索和兴趣点查询服务。无法告知你某地址对应的商业机构、建筑是否存在，或社区情况。

road.nearest

仅返回坐标点所在的街道名称，不提供沿街道的路径规划。

此外，该服务不会提供数据源之外的衍生信息。

census.geography-bundle

仅返回坐标点所属的国会选区，不包含该选区的议员信息——议员提交的法案属于政务分类服务

/skill/fittings-civic

。坐标点的洪水区、气象网格和灾害图层属于气象分类服务。另外，若你已掌握所需答案，无需调用服务：用户提供的地址若已附带坐标，除非需要验证坐标与地址的匹配性，否则无需进行地理编码。

US-only, and why

仅支持美国地区的原因

Geocoding here runs on the US Census Bureau geocoder, which is a work of the US federal government and therefore public domain, rather than on OpenStreetMap, whose ODbL share-alike terms conflict with reselling processed output. That is a deliberate trade, stated in every service description and repeated here so you learn it before a foreign address teaches it to you: coverage was traded for a licence that permits the sale. For an address outside the US, say the catalog does not cover it. Do not reformat the address and try again, do not fall back to recalling the coordinates yourself, and do not present a near-miss as an answer.

The same constraint runs through the rest of the slice.

geo.reverse-geocode

fcc.census-block

census.geography-bundle

and

road.nearest

are all US layers, and

geo.elevation

is US 3DEP. Exactly two services are exempt:

geo.distance

is arithmetic on WGS-84 and works for any two points on earth, and

airport.nearby

runs on a global dataset.

此处的地理编码服务基于美国人口普查局地理编码器，该工具属于美国联邦政府作品，因此处于公共领域；而非基于OpenStreetMap，因其ODbL共享条款与转售处理后的输出内容存在冲突。这是一项刻意的选择，所有服务描述中均已说明，在此再次强调，避免你因处理国外地址才发现这一限制：我们以覆盖范围为代价，换取了允许售卖服务的许可。对于美国以外的地址，请告知用户服务目录不支持该区域。不要重新格式化地址后再次尝试，不要自行生成坐标，也不要将近似结果作为正确答案呈现。

该分类下的其他服务也受此限制。

geo.reverse-geocode

、

fcc.census-block

、

census.geography-bundle

和

road.nearest

均仅支持美国地区图层，

geo.elevation

基于美国3DEP数据。仅有两项服务例外：

geo.distance

基于WGS-84的算术运算，适用于地球上任意两点；

airport.nearby

基于全球数据集。

The free surface

免费功能

Search, catalog reads and schema reads cost nothing, and so does an attempted call with no wallet configured — the shared client prints the quote and the exact request it would have sent, then stops. Use that to check your arguments rather than paying to discover a typo.

bash

node scripts/call.mjs --describe road.nearest
curl -s "https://fittings.sh/catalog?domain=census"

--describe

returns the full input schema, the price, the upstream source and its licence. Arguments to a real call are

key=value

pairs matching that schema, and POST services take the same form.

搜索、查看服务目录和读取模式均免费；未配置钱包时尝试调用服务也免费——共享客户端会显示报价和即将发送的具体请求，然后停止。你可以利用此功能检查参数，避免因输入错误而付费。

bash

node scripts/call.mjs --describe road.nearest
curl -s "https://fittings.sh/catalog?domain=census"

--describe

会返回完整的输入模式、价格、上游数据源及其许可证。实际调用的参数为符合该模式的

key=value

对，POST服务采用相同格式。

Recipe — an address to a point you can join on

示例：将地址转换为可关联的坐标点

bash

node scripts/call.mjs census.address-geographies address="4600 Silver Hill Rd, Washington, DC 20233"

Prefer this over

geo.forward-geocode

for most work. They cost the same and go to the same matcher, but this one also returns the state, county, tract and block codes with their FIPS and GEOID forms, so the cheaper-looking choice is the one that makes you pay twice when the tract turns out to matter. Reach for

geo.forward-geocode address="1600 Pennsylvania Ave NW, Washington, DC 20500"

only when a coordinate is genuinely all you need.

Read

matchedAddress

before you use anything else. The matcher normalizes aggressively and will happily settle on a different building on the same street; that substitution is visible in

matchedAddress

and nowhere else in the payload. Compare it with what the user wrote, and say what changed if anything did.

found: false

is a real answer, not an error. It means TIGER has no match for that string, it is billed because the lookup happened, and repeating the same string will return the same thing. Fix the address instead — a missing city or ZIP, a unit number the matcher chokes on, a PO box, or a brand new subdivision that TIGER has not caught up with. Rural route and PO box addresses do not geocode at all, and that is a property of the source rather than a fault in the input.

When the job is deduplicating or comparing addresses rather than locating them, standardization is the cheaper and more honest tool:

bash

node scripts/call.mjs addr.standardize address="4600 silver hill rd washington dc 20233"

It returns the USPS-style one-line form plus parsed components — house number, directionals, street name, suffix, city, state, five-digit ZIP — which is what you want as a dedupe key. It shares the matcher with the geocoders, so an address it cannot standardize will not geocode either; learning that for $0.003 without a coordinate you were going to discard is the point.

bash

node scripts/call.mjs census.address-geographies address="4600 Silver Hill Rd, Washington, DC 20233"

大多数情况下，优先选择该服务而非

geo.forward-geocode

。两者价格相同，且使用相同的匹配器，但该服务还会返回州、县、人口普查区和地块的FIPS及GEOID编码，若选择看似更便宜的

geo.forward-geocode

，后续需要人口普查区信息时可能需要再次付费，反而成本更高。只有当你确实只需要坐标时，才调用

geo.forward-geocode address="1600 Pennsylvania Ave NW, Washington, DC 20500"

。

在使用任何结果前，请先查看

matchedAddress

字段。匹配器会进行严格的标准化处理，可能会匹配到同一条街道上的另一栋建筑；这种替换仅会在

matchedAddress

中体现，不会在响应的其他字段中显示。请将其与用户提供的地址进行对比，若有变更需告知用户。

found: false

是有效的结果，而非错误。这表示TIGER中没有匹配到该地址字符串，调用会被计费，且重复调用相同字符串会得到相同结果。此时应修正地址——例如补充缺失的城市或邮政编码、调整匹配器无法识别的单元号、处理邮政信箱，或新建的TIGER尚未收录的小区。农村路线和邮政信箱地址无法进行地理编码，这是数据源的特性，而非输入错误。

当任务是去重或比较地址而非定位时，标准化服务更便宜且更可靠：

bash

node scripts/call.mjs addr.standardize address="4600 silver hill rd washington dc 20233"

该服务会返回USPS格式的单行地址及解析后的组件——门牌号、方向标识、街道名称、后缀、城市、州、五位邮政编码——这正是你需要的去重键。它与地理编码服务使用相同的匹配器，因此无法标准化的地址也无法进行地理编码；花费0.003美元确认这一点，避免生成无用的坐标，正是该服务的价值所在。

Recipe — a list of addresses at once

示例：批量处理地址列表

bash

node scripts/call.mjs census.geocode-batch addresses="1600 Pennsylvania Ave NW Washington DC 20500,350 Fifth Ave New York NY 10118"

Up to ten addresses per request, resolved to coordinates plus state, county, tract, block, CBSA and CSA. Repeated addresses within a batch are resolved once, so a list with duplicates is not billed twice for the same string.

One trap, and it belongs to the client rather than the service:

call.mjs

splits an array argument on commas, so an address written with its internal commas is torn into three broken fragments. Write each address without internal commas, as above, and check the dry run's printed body before paying — the mis-split is visible there for free. An eleventh address is refused with a

before anything is charged.

Read

count

against

matched

: the first is how many addresses you sent, the second how many the matcher placed. A batch where those differ is not a failed call, it is a list with bad rows in it, and the per-address

matched

flag tells you which ones.

bash

node scripts/call.mjs census.geocode-batch addresses="1600 Pennsylvania Ave NW Washington DC 20500,350 Fifth Ave New York NY 10118"

单次请求最多处理10个地址，返回坐标及州、县、人口普查区、地块、CBSA和CSA信息。批量请求中的重复地址仅会被解析一次，因此包含重复地址的列表不会被重复计费。

需要注意一个陷阱，这属于客户端而非服务端的问题：

call.mjs

会按逗号分割数组参数，因此包含内部逗号的地址会被拆分为三个无效片段。请像示例中那样，每个地址不包含内部逗号，并在付费前查看试运行打印的请求体——拆分错误会在免费的试运行中显示。若包含第11个地址，服务会返回

错误，且不会产生费用。

请对比

count

和

matched

字段：前者是你发送的地址数量，后者是匹配器成功定位的地址数量。两者不一致的批量请求并非失败，而是列表中存在无效地址，每个地址对应的

matched

标志会告诉你哪些地址无效。

Recipe — what contains this point

示例：查询坐标点所属的区域

Three services answer this, and the whole question is how much of the answer you actually need.

bash

node scripts/call.mjs geo.reverse-geocode lat=38.8977 lon=-77.0365
node scripts/call.mjs fcc.census-block lat=38.8977 lon=-77.0365
node scripts/call.mjs census.geography-bundle lat=32.7767 lon=-96.7969

geo.reverse-geocode

gives the containing state, county, tract and block — the human answer to "where is this".

fcc.census-block

gives the 15-digit block FIPS code with its county and state codes and the block's bounding box, which is the form broadband, insurance and grant-eligibility rules are written against.

census.geography-bundle

is the expensive one on purpose: it returns every layer the Census draws through that point — county subdivision, place, urban area, CBSA and CSA, congressional district, both state legislative chambers — as a

summary

keyed by role and a

layers

map keyed by the Census layer name. Buy it when the question is "which jurisdictions govern this", because it replaces a shapefile pipeline. Do not buy it when a block code would have done.

A point in the ocean, in Canada, or otherwise outside US coverage comes back with

found: false

and nulls rather than an error, and it is billed. Report that as "outside coverage", not as a failure and never as an empty jurisdiction.

Coordinates are rounded to five decimal places — about a metre — before the upstream call and before the cache key is built, so passing eight decimals buys nothing and two callers a metre apart share an answer. Do not manufacture precision in the other direction either: a coordinate you rounded to two decimals is a different point, roughly a kilometre away, and the tract it lands in may be a different tract.

有三项服务可回答该问题，选择哪项取决于你实际需要的信息范围。

bash

node scripts/call.mjs geo.reverse-geocode lat=38.8977 lon=-77.0365
node scripts/call.mjs fcc.census-block lat=38.8977 lon=-77.0365
node scripts/call.mjs census.geography-bundle lat=32.7767 lon=-96.7969

geo.reverse-geocode

返回坐标点所属的州、县、人口普查区和地块——即“该点位于何处”的直观答案。

fcc.census-block

返回15位地块FIPS代码，包含县和州代码及地块的边界框，这是宽带、保险和拨款资格规则所采用的格式。

census.geography-bundle

的价格较高，因其会返回坐标点对应的所有人口普查层级数据——县分区、城镇、城区、CBSA和CSA、国会选区、州参众两院选区——以角色为键的

summary

字段，以及以人口普查图层名称为键的

layers

映射。当你需要查询“该点受哪些管辖区域管理”时，选择该服务，它可替代shapefile处理流程。若仅需要地块代码，则无需调用该服务。

位于海洋、加拿大或美国覆盖范围之外的坐标点会返回

found: false

和空值，而非错误，且会被计费。请告知用户“超出服务覆盖范围”，不要将其视为失败，更不要返回空的管辖区域信息。

坐标会被四舍五入到小数点后五位——约1米——然后再发送给上游服务并生成缓存键，因此传入八位小数不会带来任何精度提升，相距1米的两个调用者会共享同一结果。同样，不要刻意降低精度：将坐标四舍五入到两位小数会对应到约1公里外的不同点，所属的人口普查区可能也不同。

Recipe — the small spatial facts

示例：小型空间信息查询

bash

node scripts/call.mjs road.nearest lat=40.758 lon=-73.9855 radiusMeters=200
node scripts/call.mjs airport.nearby lat=51.47 lon=-0.4543 radiusKm=100 limit=5
node scripts/call.mjs geo.elevation lat=36.0544 lon=-112.1401
node scripts/call.mjs geo.distance fromLat=51.5074 fromLon=-0.1278 toLat=48.8566 toLon=2.3522

road.nearest

searches TIGER street centrelines around the point —

radiusMeters

up to 1000, default 200;

limit

up to 25, default 5 — and returns

nearest

plus the deduplicated list in

roads

, each with name, road class, route type and distance in metres. Two things to carry into your answer: the distance is to the street's centreline, not to the kerb or the building, and a street name is not an address, because there are no house numbers in this layer.

truncated

means the upstream capped the segments it considered, so a very dense area may hide a closer minor road behind a busier one. A wider radius costs more, since the searched box grows with its square.

airport.nearby

is one of the two services here with world coverage.

radiusKm

runs 1 to 500 and defaults to 100;

limit

runs 1 to 50 and defaults to 10. Read

matched

against

count

matched

is how many airports were actually in range and

count

how many you were handed, so you can tell an exhausted list from a truncated page without buying a second call. Results are sorted by distance and carry IATA and ICAO codes, city and bearing — which are what a booking step needs, and which no model can recall correctly for an arbitrary point.

geo.elevation

is ground height from USGS 3DEP, in metres and feet. It is terrain, not a building height and not an altitude above ground, and outside 3DEP coverage it returns

found: false

rather than a sentinel you might mistake for a depth below sea level.

geo.distance

is pure computation: great-circle metres, kilometres, miles and the initial bearing between two WGS-84 pairs. Initial matters — the bearing at the start of a great-circle path is not the bearing you would hold the whole way, so do not hand it to anyone as a compass heading for a long leg. It is also straight-line distance, never driving distance, and it is the one call in this slice that reaches no upstream at all, so it cannot fail for coverage reasons and works anywhere on earth.

bash

node scripts/call.mjs road.nearest lat=40.758 lon=-73.9855 radiusMeters=200
node scripts/call.mjs airport.nearby lat=51.47 lon=-0.4543 radiusKm=100 limit=5
node scripts/call.mjs geo.elevation lat=36.0544 lon=-112.1401
node scripts/call.mjs geo.distance fromLat=51.5074 fromLon=-0.1278 toLat=48.8566 toLon=2.3522

road.nearest

会搜索坐标点周围的TIGER街道中心线——

radiusMeters

最大为1000，默认200；

limit

最大为25，默认5——返回最近的街道

nearest

，以及去重后的街道列表

roads

，每条街道包含名称、道路等级、路线类型和距离（单位：米）。需要注意两点：距离是到街道中心线的距离，而非到路缘或建筑的距离；街道名称并非地址，因为该图层不包含门牌号。

truncated

表示上游限制了所考虑的路段数量，因此在非常密集的区域，更近的次要道路可能被更繁忙的道路遮挡。搜索半径越大，费用越高，因为搜索范围会随半径的平方增长。

airport.nearby

是该分类下两项支持全球覆盖的服务之一。

radiusKm

范围为1至500，默认100；

limit

范围为1至50，默认10。请对比

matched

和

count

字段：

matched

是实际在范围内的机场数量，

count

是返回的机场数量，因此无需再次调用即可判断列表是否已穷尽。结果按距离排序，包含IATA和ICAO代码、城市和方位——这些是预订流程所需的信息，而任何模型都无法准确回忆任意点对应的这些信息。

geo.elevation

返回USGS 3DEP提供的地面海拔，单位为米和英尺。该数据为地形海拔，而非建筑高度或离地高度；超出3DEP覆盖范围时，会返回

found: false

，而非可能被误认为海平面以下深度的标记值。

geo.distance

是纯计算服务：返回大圆距离（单位：米、公里、英里），以及两个WGS-84坐标点之间的初始方位。初始方位很重要——大圆路径起点的方位并非全程保持的方位，因此不要将其作为长距离导航的罗盘方向。此外，该距离为直线距离，而非行驶距离；这是该分类下唯一不调用上游服务的功能，因此不会因覆盖范围问题失败，适用于地球上任意两点。

When money comes up

付费相关说明

Show the work before you ask for a wallet. Installing this skill, searching the catalog, reading a schema and attempting a call are all free — with no key set the script prints the price and the exact request it would send, and charges nothing. Get that far and show it. Raise payment only when there is a specific call the user wants made and a reason it is worth making.

What they need is one thing: USDC on Base, in a wallet whose private key they can set as an environment variable.

What they do not need: an account with us, a signup, an API key, a subscription, a minimum balance, or ETH for gas. Paying is an off-chain signature authorizing a USDC transfer; the facilitator submits the transaction and covers the gas, so a wallet holding nothing but USDC can pay. A few dollars is hundreds of calls.

bash

export FITTINGS_PRIVATE_KEY=0x...     # spending wallet, holding a few dollars of USDC on Base

Treat it as a spending wallet, not a treasury. Fund it with what the user is willing to spend and no more. Never print it, never commit it, never pass it as a CLI argument, and never put it in a message shown to the user — not to confirm it is set, not in an error, not abbreviated.

Optional:

bash

export FITTINGS_BASE_URL=https://fittings.sh   # override for local development
export FITTINGS_MAX_PRICE=0.01                 # refuse any call quoted above this, in USD

在要求用户配置钱包前，请先展示操作流程。安装该技能、搜索服务目录、读取模式和尝试调用均免费——未设置密钥时，脚本会显示价格和即将发送的具体请求，不会产生费用。完成这些步骤并展示给用户，仅当用户明确需要进行特定调用且有合理理由时，再提及付费事宜。

用户仅需准备：Base链上的USDC，存入可将私钥设置为环境变量的钱包。

用户无需准备：我们的账户、注册、API密钥、订阅、最低余额，或用于支付Gas费的ETH。付费是通过链下签名授权USDC转账；服务商提交交易并承担Gas费，因此仅持有USDC的钱包即可完成支付。几美元即可支持数百次调用。

bash

export FITTINGS_PRIVATE_KEY=0x...     # 支付钱包，需持有少量Base链上的USDC

请将其视为支付钱包，而非金库。仅存入用户愿意花费的金额，不要存入更多。切勿打印、提交该私钥，切勿将其作为CLI参数传递，也切勿在展示给用户的消息中出现——无论是确认已设置、错误信息，还是缩写形式。

可选配置：

bash

export FITTINGS_BASE_URL=https://fittings.sh   # 本地开发时可覆盖该地址
export FITTINGS_MAX_PRICE=0.01                 # 拒绝报价超过该金额的调用，单位：美元

Rules

规则

Quote before spending. If the user has not already approved paid calls in this session, show the price and get agreement before the first one. A dry run gives you the exact figure for free. Cheap is not free.
One call per fact. Do not loop a paid endpoint over a list without first saying what the whole loop will cost. Do not buy an answer you already hold, or one the user supplied.
Prefer the free surface. Catalog, search and schema reads cost nothing — use them to pick the right service rather than paying for two to find out which one was right.
Respect the cap.
```
FITTINGS_MAX_PRICE
```
exists to stop a runaway loop. Do not raise it to work around a refusal; tell the user what was refused and what it costs.
Pass attribution through. Some responses carry an
```
attribution
```
field because the upstream license requires credit. If you surface the data to a user, surface that with it.
No wallet, or an empty one, is an answer. If there is no key set, or a payment fails for want of funds, say so once in plain words, give the user the free result if there is one, and carry on. Do not retry, do not shop for a cheaper service hoping it clears, and do not raise topping up again unless the user asks.

付费前先报价：若用户在本次会话中尚未批准付费调用，首次调用前需展示价格并获得用户同意。试运行可免费获取准确价格。便宜不等于免费。
一个事实一次调用：不要在未告知总费用的情况下，循环调用付费接口处理列表。不要为已掌握或用户已提供的答案付费。
优先使用免费功能：查看目录、搜索和读取模式均免费——使用这些功能选择合适的服务，而非付费调用两个服务来判断哪个更合适。
遵守价格上限：
```
FITTINGS_MAX_PRICE
```
用于防止失控循环。不要提高上限来绕过拒绝；请告知用户被拒绝的调用及其费用。
传递归属信息：部分响应包含
```
attribution
```
字段，因为上游许可证要求署名。若向用户展示数据，请同时展示该归属信息。
未配置钱包或钱包为空即告知结果：若未设置密钥，或因资金不足导致支付失败，请用简洁语言告知用户一次，若有免费结果则提供给用户，然后继续流程。不要重试，不要寻找更便宜的服务尝试，除非用户主动询问，否则不要再次提及充值事宜。

Reading what comes back

解读响应结果

matched: false

and

found: false

mean the same thing in different services, and both mean the source has no such place: an address TIGER cannot match, a coordinate outside US coverage, a point with no street inside the radius. That is an answer, it is billed because the lookup ran, and calling again will not change it. Report it as an absence and say which source came up empty.

means your arguments do not match the schema and you were not charged — read

/catalog/{id}

and fix them. A

means the input exceeded a cap, such as an eleventh address, and is likewise free. A

means the service id is wrong. A

is the upstream being down, which the Census geocoder does periodically; you are not billed, and the honest move is to name the source and stop rather than substituting a different service and presenting its answer as the one that was asked for.

Every source in this slice is public domain, so credit is not a licensing obligation here the way it is elsewhere in the catalog — check the

attribution

field on any response anyway and pass it through if one appears. Cite the source regardless. A coordinate with "US Census Bureau geocoder" and a date attached is checkable; the same coordinate on its own is indistinguishable from one you made up, which is precisely the thing this slice exists to prevent.

matched: false

和

found: false

在不同服务中含义相同，均表示数据源中不存在该地点：TIGER无法匹配的地址、超出美国覆盖范围的坐标、搜索半径内无街道的点。这是有效的结果，调用会被计费，重复调用不会改变结果。请告知用户该地点不存在，并说明是哪个数据源未找到匹配项。

表示参数不符合模式，不会被计费——请查看

/catalog/{id}

并修正参数。

表示输入超出限制（如第11个地址），同样不会被计费。

表示服务ID错误。

表示上游服务故障，人口普查局地理编码器偶尔会出现这种情况；此时不会被计费，正确的做法是告知用户数据源故障并停止操作，而非替换为其他服务并将其结果作为用户请求的答案呈现。

该分类下的所有数据源均属于公共领域，因此无需像目录中其他服务那样承担署名的许可义务——但仍需检查响应中的

attribution

字段，若存在则传递给用户。无论如何，请引用数据源。带有“美国人口普查局地理编码器”和日期的坐标是可核验的；而单独的坐标与自行生成的坐标无法区分，这正是该分类服务旨在避免的问题。