Skip to main content

Monitoring Package key usage and spend

Congratulations on your new Search API package key! Now we'll teach you how to use its features to monitor and control your usage and spend for the key.

Please note that this article is complementary to the article 'Monitoring usage and spend'.

Understanding your API key quota​

Package API keys have a specific quota (number of matches) associated with them when they are generated. The key’s quota is for the full term of the key.

API package key match limits represent the number of matches you have to use during the package period, for example:

KeyPrice per matchPackage limitPackage periodPackage Cost
Package Business$0.55150001 year$8250

To know how many matches you have left on your Package key, see the API keys page on your Pipl account.

You also can set a quota for a more specific time frame, such as 100 matches per day. Please see [setting your API key quota]monitoring-usage-and-spend#setting-your-api-key-quota).

Using the HTTP headers​

The Package key usage details are shown on every API response in the HTTP header :

  • "X-Package-Allotted" —The total number of matches defined on the key.
  • "X-Package-Current" —The number of used matches.
  • "X-Package-Expiry" —The date and time when the key and remaining matches will expire.

Every billable response (i.e. every match) you get from the API will be counted against the package key limit and will be added to the "X-Package-Current".

Applying the example used in the table above, the headers will return as follows:

X-Package-Allotted  12500
X-Package-Expiry	2018-10-08 00:00:00+00:00 ##1 year from issue date##
X-Package-Current   16 ##after 16 matches were returned##

Use these three headers to calculate relevant values for your business. For example:

  1. Calculate the number of queries you have left before your package key expires:
    Queries Remaining = X-Package-Alloted - X-Package-Current

  2. Calculate the current spend on your package key:
    Current Spend = Price-per-match/*_ x X-Package-Current
    *Depending on the key you used

Example Python code​

The 'moneyed' and 'decimal' libraries are used to help handle the calculation and presentation.

from piplapis.error import APIError
from piplapis.search import SearchAPIRequest
from piplapis.search import SearchAPIResponse
from piplapis.data import Person
from piplapis.data.fields import Address, Email, Name, Phone
from moneyed import Money
from decimal import *

person = Person()
person.emails.append(Email('clark.kent@example.com'))
SearchAPIRequest.set_default_settings(api_key='YOUR_PACKAGE_KEY_HERE')
request = SearchAPIRequest(person=person)
response = request.send()


# Plain messages
print("This is your Quota for the key: ", response.package_allotted)
print("This is your usage of the key: ", response.package_current)
print("This is when the key and quota expire: ", response.package_expiry)

# Calculated messages
usagePercent = Decimal(Decimal(response.package_current)/Decimal(response.package_allotted))
keyPrice = Decimal('0.40')
totalUsage = Money(amount=(keyPrice*response.package_current),currency='USD')
print("You have used ", response.package_current," of ",response.package_allotted,"queries.")
print("You have used ",usagePercent,"% of your quota")