Geocoding API

The SearchStax Site Search solution provides a Geocoding API service that accepts city names, postal codes, or geographic coordinates (“latitude,longitude”) and returns the corresponding standardized location data, such as the nearest city, postal code, or coordinate pair.

The two main features supported by the SearchStax Geocoding API are:

  • Forward geocoding – Convert city names or postal codes to approximate geographic coordinates (“latitude,longitude”).
  • Reverse geocoding – Convert geographic coordinates (“latitude, longitude”) to the closest postal code and human-readable location data.

Premium and Advanced Accounts Only

The SearchStax Site Search Location-based search features are available to Premium and Advanced accounts, as noted on our Pricing page.

How to Use the SearchStax Geocoding API

To use the SearchStax Geocoding API, you must have the following:

  • Location-based Search must be enabled for your account.
  • Geocoding URLs – To find the SearchStax Geocoding API URLs (forward and reverse), navigate to Site Search > App Settings > All APIs > Geocoding.
  • Discovery API Key – The Discovery API key authenticates a geocoding request. The Discovery API Key is on the same page as the SearchStax Geocoding URL, under the Discovery tab.

Forward Geocoding

When using the forward geocoding service, users will input city names or postal codes and receive a list of possible matches. Each match will include geographic coordinates (“latitude,longitude”) and a formatted address.

Request

A forward geocoding request will have the following format:

curl -H "Authorization: Basic <DISCOVERY_API_KEY>" \
  "http://geocoding.searchstax.com/forward?location=<CITY_OR_POSTAL_CODE>&components=country:<COUNTRY_CODE>&app_id=<APP_ID>"

Example:

curl -H "Authorization: Basic 123qwe456asd789zxc0" \
  "http://geocoding.searchstax.com/forward?location=new%20york&components=country:US&app_id=1234"

Parameters:

  1. DISCOVERY_API_KEY – The authentication key described in the previous section.
  2. CITY_OR_POSTAL_CODE – The city name or postal code entered by the user. The input can be case-insensitive and, for the US, may include the state abbreviation (for example, “El Segundo, CA”).
  3. COUNTRY_CODE – The two-letter country code is used as a filter to limit the scope of the search.
    • If the country code is not included, US will be used by default.
    • Two-letter country codes are listed under ISO 3166-1 alpha-2.
  4. APP_ID – Your Site Search App ID. This is included in your Geocoding URL, described in the previous section.

Response

SearchStax Geocoding responses are returned in JSON format. In the following example, the API returns a response for the location 95139 in the US.

curl -H "Authorization: Token <API_KEY>" "http://geocoding.searchstax.com/forward?location=95139&components=country:US&app_id=1234"
{
  "results": [
    {
      "address_components": [
        {
          "long_name": "San Jose",
          "short_name": ""
        },
        {
          "long_name": "Santa Clara",
          "short_name": "085"
        },
        {
          "long_name": "California",
          "short_name": "CA"
        },
        {
          "long_name": "",
          "short_name": "US"
        }
      ],
      "formatted_address": "San Jose, CA 95139, US",
      "geometry": {
        "lat": 37.2252,
        "lng": -121.7687
      }
    }
  ],
  "status": "OK",
  "attribution": "Data source: GeoNames (https://www.geonames.org) - CC BY 4.0"
}

In the next example, the SearchStax Geocoding API returns a response for the location El Segundo in the US.

curl -H "Authorization: Token <API_KEY>" "http://geocoding.searchstax.com/forward?location=el%20segundo&components=country:US&app_id=1234"
{
  "results": [
    {
      "address_components": [
        {
          "long_name": "El Segundo",
          "short_name": ""
        },
        {
          "long_name": "CA",
          "short_name": ""
        },
        {
          "long_name": "US",
          "short_name": ""
        }
      ],
      "formatted_address": "El Segundo, CA US",
      "geometry": {
        "lat": 33.91918,
        "lng": -118.41647
      }
    }
  ],
  "status": "OK",
  "attribution": "Data source: GeoNames (https://www.geonames.org) - CC BY 4.0"
}
  • "results" – contains a list of matches containing address components, the human-readable formatted address, and the latitude/longitude information.
  • "status" – contains either "OK" or "ZERO_RESULTS".
  • "attribution" – contains attribution information.

Reverse Geocoding

The reverse geocoding service accepts a lat_lon pair as input and returns a postal code.

Request

curl -H "Authorization: Token <API_KEY>" \
  "http://geocoding.searchstax.com/reverse?location=<LAT_LON>&components=country:<COUNTRY>&app_id=1234"

Example:

curl -H "Authorization: Token 123qwe456asd789zxc0" \
  "http://geocoding.searchstax.com/reverse?location=33.916993,-118.391433&components=country:US&app_id=1234"

Parameters:

  1. DISCOVERY_API_KEY – The authentication key described previously.
  2. LAT_LON – The latitude/longitude used for search. The input should be in the format latitude,longitude.
  3. COUNTRY_CODE – The two-letter country code is used as a filter to limit the scope of the search.
    • If the country code is not included, US will be used by default.
    • Two-letter country codes are listed under ISO 3166-1 alpha-2.
  4. APP_ID – Your Site Search App ID. This is included in your Geocoding URL, described previously.

Response

SearchStax Geocoding responses are returned in JSON format. In the following example, the API returns a response for the location 33.916993,-118.391433.

curl -H "Authorization: Token <API_KEY>" "http://geocoding.searchstax.com/reverse?location=33.916993,-118.391433&components=country:US&app_id=1234"
{
  "results": [
    {
      "address_components": [
        {
          "long_name": "El Segundo",
          "short_name": ""
        },
        {
          "long_name": "Los Angeles",
          "short_name": "037"
        },
        {
          "long_name": "California",
          "short_name": "CA"
        },
        {
          "long_name": "",
          "short_name": "US"
        }
      ],
      "formatted_address": "El Segundo, CA 90245, US",
      "geometry": {
        "lat": 33.9243,
        "lng": -118.4119
      }
    }
  ],
  "status": "OK",
  "attribution": "Data source: GeoNames (https://www.geonames.org) - CC BY 4.0"
}
  • "results" – contains a list of matches containing address components, the human-readable formatted address, and the latitude/longitude information.
  • "status" – contains either "OK" or "ZERO_RESULTS".
  • "attribution" – contains attribution information.

Questions?

Do not hesitate to contact the SearchStax Support Desk.