openapi: 3.0.3 info: title: Acuris Geo API description: | REST API for **address validation**, **geocoding**, and **address suggestions** across supported countries (see **Country codes** below). ### Authentication Present your API key using any of the following (listed in priority order): - **`Authorization: Bearer `** header — recommended; standard OAuth-style bearer. - **`X-API-Key: `** header. - **`?password=`** query parameter (legacy; also accepts `?key=`). - **`{"key": "..."}`** or **`{"password": "..."}`** JSON body field on `POST /validate` (legacy). Header auth is preferred: query-param secrets can leak into access logs, Referer headers, and browser history. Without a key, **anonymous free tier** limits apply per client IP (see `/validate-credits`, `/geocode-credits`, and [Pricing](https://www.acuris-geo.com/acuris-pricing/)). #### RapidAPI When consumed via the RapidAPI marketplace, the RapidAPI gateway is the identity provider: it injects `X-RapidAPI-Proxy-Secret` (a shared secret verified server-side), `X-RapidAPI-Key`, `X-RapidAPI-User`, and `X-RapidAPI-Subscription` on every request. Plan quotas are enforced upstream by RapidAPI; no Acuris account or credits are required for traffic routed through RapidAPI. Direct (non-RapidAPI) calls continue to use the authentication methods above. ### Country codes (validation & geocode `country`) `usa`, `can`, `deu`, `che`, `fra` (full rooftop tier). Many additional countries have street-segment coverage; see `accuracy_type` in each response to know what tier was returned. ### Trial (registered key) - After email verification, new keys receive **1,000 validation credits** and **1,000 geocode credits**, expiring after **4 weeks** (see `trial_expires_at` from `GET /check-key`). Validations decrement `validation_credits`; geocodes decrement `geocode_credits`. ### Match quality contract (validate and geocode) Every successful or not-found response carries a machine-readable precision tier: - **`accuracy_type`** — canonical, customer-facing precision tier. Values: `rooftop` (building-level), `street_interpolated` (HNO interpolated along a street-segment polyline), `street_centroid` (street confirmed, exact HNO not in DB), `postcode_centroid` (only postcode matched), `locality_centroid` (only city/locality matched), `admin_centroid` (only admin region matched), or `null` on `no_match`. **Use this field for client-side branching.** - `match_type` — internal/legacy tier with a numeric score table: `rooftop` (1.0), `parcel_centroid` (0.9), `interpolated` (0.8), `street_level` (0.6), `zip_centroid` (0.4), `city_centroid` (0.2), `no_match` (0.0). Retained for backward compat; `accuracy_type` is the recommended field. - `match_score` — float `0.0`–`1.0` mirroring `match_type`. - `match_components` — object indicating which input fields were confirmed by the match. - `input_corrected` — `true` when any input field was normalized or corrected. **Cascade behavior on geocode:** when the addresses DB has no rooftop record for the submitted address, the engine falls back to a street-segment DB (SEG) and emits the highest-precision tier available (interpolated → street centroid → postcode centroid → locality centroid). `/validate` follows the same cascade for the returned `lat`/`lng`, but `confidence_level` (A/B/C/F) reflects whether the address was *confirmed*, not where the coordinate came from — SEG-derived results stay at C/F since SEG can attest to plausibility but not existence. Validation also exposes: - `suggestions` — ranked near-misses when exact match fails, or alternates when a fuzzy match succeeds. - `alternative_matches` — same street + house number found in a different state (USA / CAN only). - `reasons` — failure classifications on 404 (`street_not_found`, `city_not_matching`, `locality_unknown`). - `match_type_legacy` / `match_score_legacy` — retained for backward compatibility with pre-2026 clients (old values: `exact` / `fuzzy`, and the string label `"Perfect match"`, etc.). ### Service level - **Uptime target: 99.9% monthly**, measured continuously by our public status page at [acuristatus.instatus.com](https://acuristatus.instatus.com) with independent monitors for `/ping`, `/validate-credits`, `/geocode-credits`, and `/docs`. - **Latency target: p95 < 500 ms** for `/validate` and `/geocode` against the primary reference region under normal load. - **Scheduled maintenance** is announced on the status page at least **24 hours in advance** and is excluded from the uptime calculation. - **Rate-limit responses (429)** are not counted as downtime. - Enterprise customers may negotiate a contractual SLA with uptime credits — [contact support](https://api.acuris-geo.com/support). ### HTTP status codes - **200** match found. - **400** missing required field (e.g. `country`, or `street`/`city` on validate). - **401** invalid or inactive API key. - **403** insufficient credits, trial expired, or anonymous limit reached. - **404** address not found. Response body still includes `match_type: "no_match"`, plus `suggestions` and `reasons` when available. - **422** input could not be parsed (e.g. `input` was neither a string nor an object on `/validate`). - **429** rate limit exceeded (`rate_limit_exceeded`). - **501** reverse geocoding not yet enabled for this country (spatial index missing). - **503** reference database not available on this deployment. - **504** validation timed out. Human-friendly **register / login** flows: HTML pages at `/register` and `/login` (browser). Obtain an API key from the customer dashboard after signup. version: "1.0.0" contact: name: Acuris Geo url: https://api.acuris-geo.com/support servers: - url: https://api.acuris-geo.com description: Production security: - bearerAuth: [] - apiKeyHeader: [] - apiKeyQueryLegacy: [] - {} # anonymous free tier (per-IP limits apply) tags: - name: Validation description: Address validation and free-tier credits - name: Geocoding description: Rooftop / reference-database geocoding - name: Suggest description: Autocomplete-style suggestions - name: Account description: Key check and account-related helpers - name: Config description: Client configuration for forms - name: Search description: US radius search (advanced; API key usually required) paths: /validate: post: tags: [Validation] summary: Validate an address description: | Accepts a single-line address string **or** structured fields in `input`, plus required `country` (ISO-style code). **Credits:** One validation consumes one anonymous slot (if no key) or one account credit (if key valid). operationId: validateAddress requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ValidateRequest" examples: oneLine: summary: Single-line (USA) value: input: "1600 Pennsylvania Ave NW, Washington, DC 20500" country: usa keyed: summary: With API key in body value: input: "Hammerstr. 1, 67549 Worms" country: deu key: "YOUR_API_KEY" responses: "200": description: Validation succeeded content: application/json: schema: $ref: "#/components/schemas/ValidateResponse" "400": description: Missing country, unsupported country, or bad payload content: application/json: schema: $ref: "#/components/schemas/ErrorBody" "401": description: Invalid or inactive API key "403": description: Insufficient credits "404": description: "Address not found. Body includes `match_type: no_match`, `suggestions` (if any near-misses scored ≥ 0.5), and `reasons`." content: application/json: schema: $ref: "#/components/schemas/ValidateErrorBody" "422": description: Input could not be parsed (e.g. `input` was neither a string nor an object). content: application/json: schema: $ref: "#/components/schemas/ValidateErrorBody" "429": $ref: "#/components/responses/RateLimitExceeded" "504": description: Validation timed out content: application/json: schema: $ref: "#/components/schemas/ErrorBody" /validate-credits: get: tags: [Validation] summary: Free validations remaining (anonymous) description: Returns how many **free** validations remain for this IP today (UTC-based server tracking). operationId: validateCredits responses: "200": description: OK content: application/json: schema: type: object required: [free_remaining] properties: free_remaining: type: integer example: 15 "429": $ref: "#/components/responses/RateLimitExceeded" /geocode: get: tags: [Geocoding] summary: Geocode an address (all supported countries) description: | Provide `country` and address components. For countries with regions (USA, Canada), **state** / province is required together with city and street. **Credits:** One geocode consumes one free slot or one account credit (`password`). operationId: geocode parameters: - $ref: "#/components/parameters/Password" - name: country in: query required: true schema: type: string example: usa - name: street in: query required: true schema: type: string - name: hno in: query schema: type: string description: House number - name: city in: query schema: type: string description: City or locality (USA/CAN style) - name: town in: query schema: type: string description: Alternative to `city` for some countries - name: state in: query schema: type: string description: State (USA) or province (Canada) - name: postalcode in: query schema: type: string - name: db_version in: query schema: type: string description: Ignored. Reference DBs are configured at server startup via ref_dbs.json under GEOCODE_REF_DB_ROOT. responses: "200": description: Geocode result content: application/json: schema: $ref: "#/components/schemas/GeocodeResponse" "400": description: Missing parameters "403": description: Invalid key, no credits, or anonymous geocode limit reached "404": description: "Address not found. Body carries `match_type: no_match`, zeroed `match_score`, and a full-false `match_components`." content: application/json: schema: $ref: "#/components/schemas/GeocodeErrorBody" "429": $ref: "#/components/responses/RateLimitExceeded" "503": description: Reference database not available on this deployment /geocode-usa: get: tags: [Geocoding] summary: Geocode (United States shorthand) description: Same as `/geocode?country=usa` with `city` and `state` parameters. operationId: geocodeUsa parameters: - $ref: "#/components/parameters/Password" - name: street in: query required: true schema: type: string - name: hno in: query schema: type: string - name: city in: query required: true schema: type: string - name: state in: query required: true schema: type: string responses: "200": description: Geocode result with coordinates and `accuracy_type` precision tier. content: application/json: schema: $ref: "#/components/schemas/GeocodeResponse" "400": description: Missing parameters "403": description: Limit or credits "404": description: "Address not found. Body carries `match_type: no_match`, zeroed `match_score`, and a full-false `match_components`." content: application/json: schema: $ref: "#/components/schemas/GeocodeErrorBody" "429": $ref: "#/components/responses/RateLimitExceeded" /reverse: get: tags: [Geocoding] summary: Reverse geocode (coordinates → nearest address) description: | Finds the nearest known address to a given `lat`/`lng` within `radius_m` metres from the reference database. Results are sorted by distance ascending and include a `distance_m` field. **Credits:** Billed **per returned address**, not per request. A call with `limit=3` that returns 3 results decrements 3 geocode credits. The actual number charged is echoed as `units_charged` in the response body. On keyed traffic the call is pre-capped so it never overdraws the remaining balance. **RapidAPI note:** For traffic routed through the RapidAPI gateway, `limit` is forced server-side to **1** so that one HTTP request maps to exactly one `Geocoding Lookups` meter decrement. The `limit` query parameter is silently ignored for RapidAPI clients. **Availability:** Enabled per country as spatial indexes roll out. Countries without the `(RT_LAT, RT_LNG)` index return **501** `reverse_not_available` until the index is built server-side. Currently available for: `usa`. operationId: reverseGeocode parameters: - name: country in: query required: true description: Country code (see **Country codes** above). schema: type: string example: usa - name: lat in: query required: true schema: type: number format: float minimum: -90 maximum: 90 example: 38.8977 - name: lng in: query required: true schema: type: number format: float minimum: -180 maximum: 180 example: -77.0365 - name: radius_m in: query description: Search radius in metres. Capped at `50000`. schema: type: integer minimum: 1 maximum: 50000 default: 500 - name: limit in: query description: | Max results to return. Capped at `10`. **Ignored for RapidAPI traffic** — forced to `1` to align with the per-request `Geocoding Lookups` meter. schema: type: integer minimum: 1 maximum: 10 default: 1 responses: "200": description: | Match found. When `limit=1` (default) the body is a single result; when `limit>1` the body wraps `results: []` with `count`. content: application/json: schema: $ref: "#/components/schemas/ReverseResponse" examples: singleResult: summary: Default limit=1 (flat result) value: country: usa lat: 38.897653 lng: -77.03655 distance_m: 7 accuracy_type: rooftop match_type: rooftop match_score: 1.0 input_corrected: false street: PENNSYLVANIA AVE NW hno: "1600" city: WASHINGTON state: DC zip: "20500" query: lat: 38.8977 lng: -77.0365 radius_m: 200 free_remaining: 8 multiResult: summary: limit=3 (envelope with results array) value: count: 2 country: usa accuracy_type: rooftop match_type: rooftop match_score: 1.0 input_corrected: false query: lat: 38.8977 lng: -77.0365 radius_m: 200 results: - country: usa lat: 38.897653 lng: -77.03655 distance_m: 7 accuracy_type: rooftop match_type: rooftop match_score: 1.0 input_corrected: false street: PENNSYLVANIA AVE NW hno: "1600" city: WASHINGTON state: DC zip: "20500" - country: usa lat: 38.898123 lng: -77.034339 distance_m: 193 accuracy_type: rooftop match_type: rooftop match_score: 1.0 input_corrected: false street: PENNSYLVANIA AVE NW hno: "1500" city: WASHINGTON state: DC zip: "20005" "400": description: Missing/invalid country, lat, lng, radius_m, or limit content: application/json: schema: $ref: "#/components/schemas/ErrorBody" "401": description: Invalid or inactive API key "403": description: Insufficient credits, trial expired, or anonymous limit reached "404": description: "No address within `radius_m`. Body includes `match_type: no_match` and `reasons: [\"no_address_within_radius\"]`." content: application/json: schema: type: object properties: match_type: type: string example: no_match match_score: type: number example: 0.0 input_corrected: type: boolean example: false reasons: type: array items: type: string example: ["no_address_within_radius"] country: type: string query: type: object properties: lat: { type: number } lng: { type: number } radius_m: { type: integer } "429": $ref: "#/components/responses/RateLimitExceeded" "501": description: Reverse geocoding not yet enabled for this country (spatial index missing). content: application/json: schema: type: object properties: error: type: string example: reverse_not_available message: type: string "503": description: Reference database unavailable on this deployment. /geocode-credits: get: tags: [Geocoding] summary: Geocode free tier or key balance description: | Without `password`: returns `free_remaining` anonymous geocodes for this IP. With valid `password`: returns account `balance`; `free_remaining` may be null. operationId: geocodeCredits parameters: - $ref: "#/components/parameters/Password" responses: "200": description: Remaining anonymous free credits and (when an API key is provided) the registered key's geocode credit balance. content: application/json: schema: type: object properties: free_remaining: type: integer nullable: true example: 10 balance: type: integer description: Present when valid key supplied "429": $ref: "#/components/responses/RateLimitExceeded" /check-key: get: tags: [Account] summary: Check API key description: Returns whether the key is active and current credit balance. operationId: checkKey parameters: - name: password in: query required: true schema: type: string responses: "200": description: Key validity and remaining credit balance for the supplied API key. content: application/json: schema: oneOf: - type: object required: [valid, credits] properties: valid: type: boolean example: true credits: type: integer - type: object properties: valid: type: boolean example: false message: type: string "400": description: No key provided "401": description: Invalid key /suggest: get: tags: [Suggest] summary: Address suggestions (autocomplete) description: | Returns a list of suggestion strings for prefix `q` (or `prefix`) and `country`. Rate limited (100/day per IP by default). operationId: suggest parameters: - name: q in: query schema: type: string - name: prefix in: query schema: type: string - name: country in: query required: true schema: type: string - name: limit in: query schema: type: integer default: 10 maximum: 50 responses: "200": description: Ranked list of address suggestions matching the partial input. content: application/json: schema: type: object properties: suggestions: type: array items: $ref: "#/components/schemas/StandardizedAddress" "400": description: Unsupported country "429": $ref: "#/components/responses/RateLimitExceeded" /api/country-config: get: tags: [Config] summary: Form field order and examples description: Returns UPU-oriented field order and optional examples per country for building address forms. operationId: countryConfig responses: "200": description: Per-country form field ordering and example values for building address-entry UIs. content: application/json: schema: type: object additionalProperties: true /search: get: tags: [Search] summary: US radius search (heatmap / pins) description: | **Advanced:** primarily for internal or partner tooling. Requires a valid API key for some modes. Parameters include `city`, `state`, `radius`, `street`, `hno`, `mode` (`heatmap` | `pins`), and `password`. operationId: search parameters: - $ref: "#/components/parameters/Password" - name: city in: query schema: type: string - name: state in: query schema: type: string - name: radius in: query schema: type: number - name: street in: query schema: type: string - name: hno in: query schema: type: string - name: mode in: query schema: type: string enum: [heatmap, pins] - name: cap_to_balance in: query schema: type: string responses: "200": description: Search results (structure depends on mode) content: application/json: schema: type: object additionalProperties: true "400": description: Missing parameters "401": description: Unauthorized "429": $ref: "#/components/responses/RateLimitExceeded" components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: opaque description: | Send your API key as `Authorization: Bearer `. Recommended. apiKeyHeader: type: apiKey in: header name: X-API-Key description: | Alternative header auth: `X-API-Key: `. apiKeyQueryLegacy: type: apiKey in: query name: password description: | Legacy query-param auth (`?password=`, or `?key=`). Retained for backward compatibility; prefer header auth — query-string secrets can leak into access logs. parameters: Password: name: password in: query description: | Legacy API key query parameter. Prefer `Authorization: Bearer ` or `X-API-Key: ` header auth instead. schema: type: string responses: RateLimitExceeded: description: Too many requests (anonymous limit or WAF/limiter) content: application/json: schema: type: object properties: error: type: string example: rate_limit_exceeded message: type: string schemas: ErrorBody: type: object properties: error: type: string message: type: string MatchType: type: string description: | Internal/legacy precision tier with the score table below. New clients should prefer `accuracy_type` (Smarty-style enum) for branching. Score table: * `rooftop` → 1.0 * `parcel_centroid` → 0.9 * `interpolated` → 0.8 * `street_level` → 0.6 * `zip_centroid` → 0.4 * `city_centroid` → 0.2 * `no_match` → 0.0 enum: - rooftop - parcel_centroid - interpolated - street_level - zip_centroid - city_centroid - no_match AccuracyType: type: string nullable: true description: | Canonical, customer-facing precision tier of the returned coordinate. `null` on `no_match`. Use this field — not `match_type` — for client-side branching. * `rooftop` — building-level coordinate (RT_LAT/RT_LNG match against addresses DB). * `street_interpolated` — HNO interpolated along a street segment polyline (SEG cascade). * `street_centroid` — street confirmed; exact HNO not located. * `postcode_centroid` — only postcode matched. * `locality_centroid` — only city/locality matched. * `admin_centroid` — only admin region (state/province) matched. enum: - rooftop - street_interpolated - street_centroid - postcode_centroid - locality_centroid - admin_centroid MatchComponents: type: object description: Which input fields were confirmed by the match. required: [house_number, street, city, zip, state] properties: house_number: type: boolean street: type: boolean city: type: boolean zip: type: boolean state: type: boolean FailureReason: type: string description: | Why a validation returned 404. * `street_not_found` — no street in the candidate set scored highly. * `city_not_matching` — street looked right but the locality did not. * `locality_unknown` — we could not even find candidates in the locality. enum: - street_not_found - city_not_matching - locality_unknown StandardizedAddress: type: object description: Canonical address as stored in the reference database. properties: street: type: string house_number: type: string city: type: string state: type: string description: Present for countries with regions (USA, CAN). postcode: type: string country: type: string formatted_address: type: string description: Country-specific pretty-printed form, multi-line. Suggestion: type: object description: | A ranked near-miss or fuzzy alternative returned on `/validate`. Appears in `suggestions[]` on V2 (fuzzy) successes and on 404 near-miss responses. required: [standardized, score] properties: standardized: $ref: "#/components/schemas/StandardizedAddress" score: type: number format: float minimum: 0 maximum: 1 lat: type: number format: float lng: type: number format: float AlternativeMatch: type: object description: | Same street + same house number in a different state. Emitted on USA / CAN V1 (exact) matches only, bounded to 5 rows. required: [standardized, score] properties: standardized: $ref: "#/components/schemas/StandardizedAddress" score: type: number format: float description: Always 1.0 — these are exact DB matches in a different state. lat: type: number format: float lng: type: number format: float ValidateRequest: type: object required: [country] properties: country: type: string description: Country code (e.g. usa, deu) input: description: Single-line address string **or** object with street, house_number, city, postcode, state, etc. oneOf: - type: string - type: object additionalProperties: true key: type: string password: type: string db_version: type: string description: Ignored. Same reference DB as geocode (ref_dbs.json). ValidateResponse: type: object description: | Successful validation. The canonical form lives in `standardized` (V1 exact) or `corrected` (V2 fuzzy). All successes carry the full match-quality contract (`match_type`, `match_score`, `match_components`, `input_corrected`). additionalProperties: true required: [match_type, match_score, match_components, input_corrected, accuracy_type] properties: standardized: $ref: "#/components/schemas/StandardizedAddress" corrected: $ref: "#/components/schemas/StandardizedAddress" status: type: string enum: [V1, V2] description: V1 = exact DB match. V2 = fuzzy match above 0.85 similarity threshold. confidence: type: number format: float description: 1.0 for V1; the fuzzy similarity score (0.85–1.0) for V2. confidence_level: type: string enum: [A, B, C, F] description: Legacy A/B/C/F grading retained for bulk-CSV workflows. corrections: type: array description: Human-readable list of corrected input fields (e.g. `["Postal code", "City"]`). items: type: string accuracy_type: $ref: "#/components/schemas/AccuracyType" match_type: $ref: "#/components/schemas/MatchType" match_score: type: number format: float minimum: 0 maximum: 1 match_components: $ref: "#/components/schemas/MatchComponents" input_corrected: type: boolean match_type_legacy: type: string enum: [exact, fuzzy] description: Retained for backward compatibility. New clients should use `match_type`. match_score_legacy: type: string description: Retained for backward compatibility. Human-readable label (e.g. `"Perfect match"`, `"Partial match (street only)"`). suggestions: type: array description: Ranked fuzzy alternatives (V2). Top-1 already in `corrected`; this array is the runners-up, up to 4 items. items: $ref: "#/components/schemas/Suggestion" alternative_matches: type: array description: Same street + house number in a different state. USA / CAN V1 only. Up to 5 items. items: $ref: "#/components/schemas/AlternativeMatch" lat: type: number format: float lng: type: number format: float house_number_not_found: type: boolean postcode_corrected: type: boolean match_details: type: object description: Per-component exact-match flags from the DB lookup. additionalProperties: true credits_remaining: type: integer description: After keyed validation. validation_credits_remaining: type: integer geocode_credits_remaining: type: integer key_accepted: type: boolean GeocodeErrorBody: type: object description: | Error body for 404 on the `/geocode*` endpoints. Carries the match-quality contract so clients can key on the same fields regardless of success or failure. Unlike `ValidateErrorBody`, geocode errors do not include `suggestions` or `reasons`. required: [error, match_type, match_score, match_components, input_corrected, accuracy_type] properties: error: type: string example: Address not found accuracy_type: $ref: "#/components/schemas/AccuracyType" match_type: $ref: "#/components/schemas/MatchType" match_score: type: number format: float minimum: 0 maximum: 1 match_components: $ref: "#/components/schemas/MatchComponents" input_corrected: type: boolean ValidateErrorBody: type: object description: | Error body for 404 and 422 on `/validate`. Carries the match-quality contract so clients can key on the same fields regardless of success or failure. required: [error, match_type, match_score, match_components, input_corrected, accuracy_type] properties: error: type: string example: Address not found message: type: string accuracy_type: $ref: "#/components/schemas/AccuracyType" match_type: $ref: "#/components/schemas/MatchType" match_score: type: number format: float minimum: 0 maximum: 1 match_components: $ref: "#/components/schemas/MatchComponents" input_corrected: type: boolean reasons: type: array description: One or more classifications of why the match failed (404 only). items: $ref: "#/components/schemas/FailureReason" suggestions: type: array description: Top-3 near-miss candidates scoring ≥ 0.5 but below the 0.85 fuzzy threshold (404 only). items: $ref: "#/components/schemas/Suggestion" parsed: type: object description: If present, the parser's best-effort field breakdown of the input. additionalProperties: true GeocodeResponse: type: object additionalProperties: true required: [match_type, match_score, match_components, input_corrected, accuracy_type] properties: lat: type: number format: float lng: type: number format: float formatted_address: type: string street: type: string city: type: string description: Present for countries with regions (USA, CAN). town: type: string description: Alternative to `city` for countries without regions. state: type: string postcode: type: string hno: type: string house_number_not_found: type: boolean postcode_corrected: type: boolean matched_via_alias: type: boolean description: True when a locality alias (USPS city / CAN community) was used. usps_city: type: string locality_note: type: string city_mismatch_ignored: type: boolean description: Canada only — matched by province + street + HNO, city name ignored. accuracy_type: $ref: "#/components/schemas/AccuracyType" match_type: $ref: "#/components/schemas/MatchType" match_score: type: number format: float minimum: 0 maximum: 1 match_components: $ref: "#/components/schemas/MatchComponents" input_corrected: type: boolean balance: type: integer description: Remaining geocode credits after keyed call. validation_credits: type: integer free_remaining: type: integer ReverseResponse: description: | Reverse geocoding response. When the request's `limit=1` (default), the body is a single flat result. When `limit>1`, the body contains a `results` array of flat result objects plus `count` and top-level `match_type` / `match_score` reflecting the best (closest) match. type: object additionalProperties: true properties: country: type: string example: usa lat: type: number format: float description: Latitude of the matched address (not the query point). lng: type: number format: float distance_m: type: integer description: Distance in metres from the query point to this result. accuracy_type: $ref: "#/components/schemas/AccuracyType" match_type: $ref: "#/components/schemas/MatchType" match_score: type: number format: float input_corrected: type: boolean description: Always `false` for reverse geocoding (input is coordinates, not an address). street: type: string hno: type: string city: type: string state: type: string description: Present for countries with regions (USA, CAN). zip: type: string query: type: object description: Echo of the effective query parameters (after clamping). properties: lat: { type: number } lng: { type: number } radius_m: { type: integer } results: type: array description: Only present when `limit > 1`. items: type: object count: type: integer description: Only present when `limit > 1`; equals `results.length`. units_charged: type: integer description: | Number of geocode credits debited for this call. Equals the number of addresses returned (`count`, or `1` when the body is a flat single result). Always `1` for RapidAPI traffic. balance: type: integer description: Remaining geocode credits after keyed call. free_remaining: type: integer description: Remaining anonymous geocodes for this IP today.