Geocoding API

Updated

The Geocoding API provides forward and reverse geocoding for Site Search applications.

Use it when your Site Search experience needs to turn user-entered places into structured locations, or turn latitude and longitude coordinates into a readable place result.

Endpoints

  • Method: GET
  • Forward: https://geocoding.searchstax.com/forward
  • Reverse: https://geocoding.searchstax.com/reverse

UI Navigation

Find the forward and reverse geocoding endpoints in Site Search > App Settings > All APIs > Geocoding.

Geocoding endpoint panel in Site Search app settings.

Authentication

Use token-style Discovery authentication. 

Authorization: Token <DISCOVERY_API_KEY>

Note: Authorization: Basic <...> is not valid for these endpoints.

Find the Discovery key in Site Search > App Settings > All APIs > Discovery.

Discovery API key navigation in Site Search app settings.

Request Parameters

Name Required Type Description
Authorization Yes header Use Authorization: Token <DISCOVERY_API_KEY> for geocoding endpoint calls.
location Yes query string Forward geocoding: place text such as a postal code, city, or address fragment. Reverse geocoding: latitude,longitude coordinates.
components No query string Optional country scoping (for example, country:US).
app_id Yes query string Site Search app identifier required by geocoding endpoints.

Request Examples

Forward geocoding: 

curl -sS --get \
  -H "Authorization: Token <discovery-api-key>" \
  --data-urlencode "location=95139" \
  --data-urlencode "components=country:US" \
  --data-urlencode "app_id=<app_id>" \
  "https://geocoding.searchstax.com/forward"

Reverse geocoding: 

curl -sS --get \
  -H "Authorization: Token <discovery-api-key>" \
  --data-urlencode "location=33.916993,-118.391433" \
  --data-urlencode "components=country:US" \
  --data-urlencode "app_id=<app_id>" \
  "https://geocoding.searchstax.com/reverse"

Response Example

This sample shows a forward-geocoding response for a text location input such as a ZIP code or city name: 

{
  "status": "OK",
  "results": [
    {
      "formatted": "Los Angeles, CA, USA"
    }
  ],
  "attribution": "..."
}

Reverse-geocoding responses use the same top-level structure (status, results, and attribution), but the results array represents the resolved place for the latitude and longitude pair you submitted.

HTTP Status Codes and Error Handling

HTTP Code When It Happens Typical Response Body What to Do
200 Valid forward and reverse request JSON with status and results Process geocoding results
401 Invalid token or unsupported auth format Invalid token or unauthorized response Use Authorization: Token <key>
422 Request validation failures on required inputs Validation detail payload Send required inputs (location, app_id)
500 Server-side failure for malformed or extreme input Internal server error response Reduce input size and complexity, then retry safely
429 Shared rate and plan limit condition Too-many-requests response Retry with backoff

Note: Missing required parameters can return 401 or 422, depending on auth and validation order.

Pagination

Not applicable for geocoding responses.

Rate Limits and Backoff

  • No geocoding-specific per-endpoint rate contract is documented.
  • Follow shared app-level guidance (20+ requests/second) and 429 behavior.
  • Retry-After can be absent. Use client-side retry delays.

Shared API Foundations

Use these shared references for authentication, request and response structure, and pagination behavior used across Site Search APIs:

Articles in this section