Authentication

Every request to a public endpoint is guarded. Authentication combines two factors:

1. an API key passed as the apiKey query parameter, and
2. the calling domain, derived from the request's Referer header (falling back to the Host header).

The pair (domain, apiKey) is checked against an allow-list. A key only works from the domain(s) it was issued for.

Sending credentials

The host is normalised before matching: the port is stripped and a leading www. is removed. So https://www.yourapp.com:443/checkout is matched as yourapp.com.

Examples

cURL

Code(bash)
 
curl -G 'https://api.polaris.launify.com/address_whisper' \
  -H 'Referer: https://yourapp.com' \
  --data-urlencode 's=Národní' \
  --data-urlencode 'apiKey=YOUR_API_KEY'

JavaScript

Code(js)
 
// From the browser the Referer is set for you.
const url = new URL('https://api.polaris.launify.com/address_whisper');
url.searchParams.set('s', 'Národní');
url.searchParams.set('apiKey', 'YOUR_API_KEY');

const res = await fetch(url);
const results = await res.json();

Python

Code(python)
 
import requests

res = requests.get(
    "https://api.polaris.launify.com/address_whisper",
    params={"s": "Národní", "apiKey": "YOUR_API_KEY"},
    headers={"Referer": "https://yourapp.com"},
)
results = res.json()

Failure

If the key or domain is missing or not allow-listed, the API responds with 403 Forbidden:

Code(json)
 
{
  "statusCode": 403,
  "message": "Unauthorized"
}

A missing key or domain returns 403 with "Missing API key or domain". See Errors for the full list.