A1: Peer39 provides a response for every URL classification request in real time. When we receive a URL, our system first checks to see if the URL has been classified and exists within our Peer39-side cache.
If the URL exists in our cache, which means we have fully classified the URL and its page-level content, Peer39 responds with the full and Final classification response (RT=0). (Peer39 cache is refreshed every 24 hours, but you can configure this threshold.)
If the URL does not exist in our cache, which means it has not been fully classified, Peer39 responds with a First Look response (RT=2) or an Error response (RT=1) when applicable.
Since our API integration is designed to support URLs within the RTB environment, the submission of URLs should reflect and mimic, as closely as possible, the actual RTB volume and activity.
For clients who build a cache to store Peer39 classification results, our guideline is to send all traffic seen on a URL until receiving a Final classification response (RT=0) for the URL. (Since URLs are prioritized by volume, this will help our system prioritize the most prevalent URLs to classify first.) When you receive a Final classification response of RT=0, you can stop sending requests for that URL and cache the classification results for 24 hours. (You can configure this threshold.)
A2: A URL should be continually and repeatedly submitted until a Final classification response (RT=0) is returned. (There is one exception: You receive an Error response (RT=1), which means that something is incorrect or missing in the API call and should be corrected before a classification result is possible.)
If you implemented a client-side cache to store the Final classification result, and your cached result expires, you should resubmit the URL until you receive a Final classification response (RT=0).
Regardless of the presence of a client-side cache, we recommend that all URLs be resubmitted 24 hours after receiving a Final classification response (RT=0). This aligns with Peer39’s 24-hour cache cycle and will provide the most up-to-date classification results.
A3: You may filter out URLs that were seen only once across your traffic. Beyond that, it is not recommended to apply a minimal frequency or threshold to URLs prior to submitting them to Peer39. We recommend that you send us all your URL traffic unhindered; this will result the best classification coverage of your inventory.
After you receive a Final classification response (RT=0) for a given URL, you may choose to cache the URL and its results locally for recall, and only resubmit the URL once the cache expires.
A4: When a Final classification response (RT=0) is returned for a URL, the classification result is saved in our Peer39 cache for 24 hours. (You can configure this threshold.) After 24 hours, the final classification result is purged from our cache and URLs should be resubmitted for classification again.
A5: A First Look response, also referred to as RT=2, is only available to clients who integrate by using the API. It is an initial and simple classification of a web page based solely upon its physical URL string. We read and analyze things like the URL’s domain, directories, file extensions, and query string to provide a statistical classification that represents the general content of the page URL.
When possible, the First Look response provides a content category classification, such as News, Automotive, and Mature. Additionally, Quality attributes such as Transparent Inventory, Ad Count, and Ad Viewability, may also be included in the First Look response when possible.
When a meaningful content category cannot be determined for the URL, the default category of Other will be provided. Publisher clients can choose to designate a specific default category such as Travel, or rename the default category as needed.
Note: The First Look response does not include Safe attributes, such as Safe from Mature or Safe from Alcohol. The Safe attributes are only available in the Final response (RT=0), since they can only be confirmed once we have extracted and fully analyzed the actual content of the page. If there is enough statistical information about the URL, the First Look response may include Negative categories like Mature or Torrents.
A6: Peer39 systems are designed to provide you with the highest classiﬁcation coverage of your inventory. The First Look (RT=2) response provides a quick and general classiﬁcation in real time, while our ofﬂine classification systems work on the full-page level classiﬁcation response. First look classifications are valuable and can be used until the Final, full-page level classification result (RT=0) is available.
For example, the Fox News website includes a page about a new theme park in California. This page receives an initial First Look classification of News, which can be used for generic, top-level targeting. After the page is fully processed, the Final classification response (RT=0) will contain a complete classification of, for example, News, Travel: Theme Parks, Travel: Destination: California, Quality: CRE, and Safe from Mature, which can be used for more granular targeting and safety consideration.
A7: An Error response, also referred to as RT=1, indicates that something in the API call is incorrect, missing, and/or does not meet the minimal URL submission requirements.
An Error response will be returned when:
The API key, also known as the client code (cc), is incorrect or missing.
The URL for classification is submitted without the http:// or https:// protocol.
The URL for classification is missing a domain extension.
A8: A URL is considered as Classified when the response contains any of Peer39’s categories, contextual, quality, or safety.
A URL is considered Unclassified when either the Default classification is the only category returned in the response or when an Error response (RT=1) is returned.
A9: The Default classification implies that our system had nothing extra to report about the URL or the page-level content. A Default classification may occur when:
The page and/or the URL lacks sufficient content for Peer39 to provide a classification.
The URL is invalid (for example, missing protocol or domain extension).
A10: If you implement a client-side cache, we recommend storing URLs that have received a Final classification response (RT=0). You may cache an RT=2 response while waiting for a final classification response (RT=0), but once a Final classification response is returned for a given URL, you should store the URL and its Final classification result in your client cache for 24 hours. (You can configure this threshold.) Upon cache expiration, please resubmit the URL for updated classification.
A11: RT is short for Response Type and identifies the classification status.
First Look (Pending)
Does an initial analysis of the URL string to provide a statistical classification when applicable.
Error response for API calls or URLs that do not meet the minimal submission requirements.
Final Full Classification
Indicates that the page URL has been processed for a full page level classification. (Please remember that Final classification results are stored for 24 hours. (You can configure this threshold.))
A12: In general, any URLs that have yet to receive a Final classification response of RT=0 should be sent to Peer39 for classification. Exceptions include:
URLs that have received a Final classification response of RT=0. These URLs are fully classified and their results can be stored and recalled locally from your client-side cache. When the cache expires, please resubmit the URL for updated classification.
URLs that have received an Error response (RT=1). After correcting the API call and/or URL submission requirements, please resubmit the URL for updated classification.
A13: URLs must be submitted with a valid http:// or https:// protocol and contain a valid domain extension (for example, .com, .edu, .net). URLs that fail to meet these requirements when submitted for classification will result in an Error (RT=1) response and will need to be reevaluated and or corrected to be eligible for classification.
A14: In general, it is best not to modify or pre-clean URLs before sending to Peer39. Our technology has a highly effective URL cleaning mechanism which is included as part of our classification process; therefore, we do not require clients to pre-clean or modify URLs in any way.
Historically, we have found that, in some cases, ineffective client-side cleaning mechanisms can result in a modified URL that may direct to a different page or different content from the original URL. We do not recommend modification or pre-cleaning of the URL prior to submission.
A15: Peer39 does not aggregate globally or cache classification results across accounts. The Peer39 24-hour cache is account-specific, due to the individual nature of each account's traffic and taxonomy. (You can configure this threshold.)
A16: For Weather Targeting to desktop and laptop users, you must minimally include and pass a value for either ge= or ip=. For Weather Targeting to mobile users, you need to include and populate the ll= parameter. The zp= parameter must be passed in conjunction with the ge= or ip= parameters and their valid values to receive Weather Targeting categories.
A17: Every hour. For Weather Targeting categories to be effective, you should call us in real time with no caching, or apply a very short cache window (such as one hour).
A18: No, Weather Targeting categories are returned as regular category IDs and will not change the structure of your current API response.
A19: Weather Targeting categories are provided in both the First look (RT=2) and the Final Classification response (RT=0).
A20: Yes. Both the App ID (Bundle ID or Item ID in iTunes) and OS (iOS or Android) must be passed to get Mobile App classification. Omitting either of these values prohibits classification for the intended Mobile App and may result in an Error (RT=1) response.
A21: For Mobile App classification, the pu= parameter is still required in the API call; however, its value should remain empty. For example:
A22: If you pass values for both pu= and mo= parameters, the input value for the pu= parameter will take precedence. This means that the Page URL will take precedence over the Mobile App ID and OS and the classification response will be based solely off the Page URL input that was passed into the pu= parameter.
A23: No. Upon classification of a Mobile App, categories are returned as regular category IDs and will not change the structure of your current API response.
A24: Mobile App categories are all returned as Final response (RT=0).
A25: Due to the unique characteristics of the current Mobile App environment, the standard Peer39 Safety attributes do not apply to Mobile App classification at this time. Instead, we recommend using the Negative Apps categories to ensure that your ads are running in safe mobile environments. There are eight Negative Apps categories that are available for targeting:
Negative Apps > Alcohol
Negative Apps > Copyright Infringement
Negative Apps > Drugs
Negative Apps > Gambling
Negative Apps > Mature
Negative Apps > Profanity and Hate Speech
Negative Apps > Torrent
Negative Apps > Violence