Quick Start

In order to make your first request you need an API key. You can find create your API key by logging into your self-service dashboard.

🚧 Need an API Key

If you need an API you can sign up for an account and get your key here.

Get a Placekey for an Address

To get started you can use the below query to get a Placekey for just an address.

Example Request:

curl --location 'https://api.placekey.io/v1/placekey' \
--header 'apikey: {{apikey}}' \
--header 'Content-Type: application/json' \
--data '{
  "query": {
    "street_address": "1543 Mission Street, Floor 3",
    "city": "San Francisco",
    "region": "CA",
    "postal_code": "94105",
    "iso_country_code": "US",
    "latitude": 37.7371,
    "longitude": -122.44283
  },

curl

curl --location 'https://api.placekey.io/v1/placekey' \
--header 'apikey: {{apikey}}' \
--header 'Content-Type: application/json' \
--data '{
  "query": {
    "street_address": "1543 Mission Street, Floor 3",
    "city": "San Francisco",
    "region": "CA",
    "postal_code": "94105",
    "iso_country_code": "US",
    "latitude": 37.7371,
    "longitude": -122.44283
  }
}'

python

import requests
import json

url = "https://api.placekey.io/v1/placekey"

payload = json.dumps({
  "query": {
    "street_address": "1543 Mission Street, Floor 3",
    "city": "San Francisco",
    "region": "CA",
    "postal_code": "94105",
    "iso_country_code": "US",
    "latitude": 37.7371,
    "longitude": -122.44283
  }
})

headers = {
  'apikey': '{{api_key}}',  # Replace with your actual API key
  'Content-Type': 'application/json'
}

try:
    response = requests.post(url, headers=headers, data=payload)
    print(response.text)
    except Exception as e:
    print(e)

Example Response:

{
  "query_id": "0",
  "placekey": "0rsdbudq45@5vg-7gq-5mk",
}

Get a Placekey for an POI

Get a Placekey for a POI, a specific physical location which someone may find interesting. Restaurants, retail stores, and grocery stores are all examples of Points-of-Interest. Since the phrase is a mouthful, Point-of-Interest is often abbreviated as 'POI'.

Example Request:

curl

curl --location 'https://api.placekey.io/v1/placekey' \
--header 'apikey: {{apikey}}' \
--header 'Content-Type: application/json' \
--data '{
  "query": {
    "location_name": "San Francisco City Hall",
    "street_address": "1 Dr Carlton B Goodlett Pl",
    "city": "San Francisco",
    "region": "CA",
    "postal_code": "94102",
    "iso_country_code": "US",
    "latitude": 37.7371,
    "longitude": -122.44283,
    "place_metadata": {
      "store_id": "1234",
      "phone_number": "1234567890",
      "website": "sfgsa.org",
      "naics_code": "712120",
      "mcc_code": "9399"
    }
  }
}'

python

import requests
import json

url = "https://api.placekey.io/v1/placekey"

payload = json.dumps({
  "query": {
    "location_name": "San Francisco City Hall",
    "street_address": "1 Dr Carlton B Goodlett Pl",
    "city": "San Francisco",
    "region": "CA",
    "postal_code": "94102",
    "iso_country_code": "US",
    "latitude": 37.7793,  # Corrected latitude for accuracy
    "longitude": -122.4193,  # Corrected longitude for accuracy
    "place_metadata": {
      "store_id": "1234",
      "phone_number": "1234567890",
      "website": "sfgsa.org",
      "naics_code": "712120",
      "mcc_code": "9399"
    }
  }
})
headers = {
  'apikey': '{{apikey}}',
  'Content-Type': 'application/json'
}

try:
    response = requests.post(url, headers=headers, data=payload)
    print(response.text) #stops here at the moment
except Exception as e:
    print(e)

Example Response:

{
  "query_id": "0",
  "placekey": "223-227@5vg-7gq-tvz"
}

Get a Placekey for a pair of Coordinates

If you only have a pair of coordinates you can still get a placekey. The placekey will only contain the "where" part. If you need a refresher on the placekey structure and design visit this page.

curl

curl --location 'https://api.placekey.io/v1/placekey' \
--header 'apikey: {{apikey}}' \
--header 'Content-Type: application/json' \
--data '{
    "query": {
        "latitude": 37.7371,
        "longitude": -122.44283
    }
}'

python

import requests
import json

url = "https://api.placekey.io/v1/placekey"

payload = json.dumps({
  "query": {
    "latitude": 37.7371,
    "longitude": -122.44283
  }
})
headers = {
  'apikey': '{{apikey}}',
  'Content-Type': 'application/json'
}

try:
    response = requests.post(url, headers=headers, data=payload)
    print(response.text) #stops here at the moment
except Exception as e:
    print(e)

Example Response:

{
  "query_id": "0",
  "placekey": "@5vg-82n-kzz"
}