API
This section is for developers. If you have not read Getting started yet, it says what Neuwo returns and how else it can reach your pages.
Two APIs
Each has its own token and base URL, and a token issued for one does not work on the other. Both are issued by Neuwo together with the endpoint URL: contact Neuwo or email adops@neuwo.ai, as there is no self-service signup.
- The EDGE API takes a URL. Neuwo fetches the published page and analyses it. It is built for calls from the browser, and it is the API Bid Enrichment runs on, by both the Prebid module and the Google Ad Manager route.
- The Auto-Tagging API takes the text itself, for content that is not published yet or has no public address. It is a server-side call.
Make your first call
One request to the EDGE API, with the token and the page you want analysed:
curl -H "origin: https://example.com" "YOUR_ENDPOINT/edge/GetAiTopics?token=YOUR_TOKEN&url=https://example.com/article"Three things decide whether this works:
- The base URL is the endpoint Neuwo issued you.
ctx.neuwo.aiis the shared one; if you were given your own, use that instead. - The
originheader is required, and it names the site the request comes from. Your endpoint answers the origins it is configured for and refuses the rest. - The first call for a new URL usually returns a message instead of categories. Neuwo queues the page, which typically takes 10 to 60 seconds. Call again after that and the categories are there.
A 401 means the token is wrong or missing, and a 403 means the token is
valid but is not allowed to do this.
To analyse text rather than a published page, post it to the Auto-Tagging API with its own token:
curl -X POST "https://napi.neuwo.ai/api/aitopics/GetAiTopics?token=YOUR_AUTO_TAGGING_TOKEN" \
--data-urlencode "format=json" \
--data-urlencode "headline=Cats: The Perfect Companion for Modern Living" \
--data-urlencode "content=Cats make wonderful pets for modern households."- Send
format=json. Without it the answer comes back as XML. - The categories come back in the same call. Text is analysed while you wait, so there is nothing to call again.
- The headline is analysed with the text.
headline_weightsets how much it counts, from0(left out) to1(the headline alone); the default is0.2. See the API reference.
Read the response
Trimmed to one entry per block, this is the shape the Auto-Tagging API returns:
{
"tags": [
{
"URI": "<https://tags.neuwo.ai/masterID101332>",
"value": "Domestic Animals and Pets",
"score": "0.79728"
}
],
"brand_safety": { "BS_score": "1.0", "BS_indication": "yes" },
"marketing_categories": {
"iab_tier_1": [{ "ID": "IAB16", "label": "Pets", "relevance": "0.54" }]
},
"smart_tags": [{ "ID": "123", "name": "animals-group" }]
}tagsis the subject in Neuwo's own vocabulary, each with a unique ID and a score. The Auto-Tagging API names the IDURIand wraps it in angle brackets; treat it as an opaque string.brand_safetycomes back in one of two shapes, eitherBS_scoreandBS_indication, which is what the Auto-Tagging API returns, orscoreandindication, so read it defensively.marketing_categoriesholds the standard sets:iab_tier_1toiab_tier_3,iab_audience_tier_3toiab_audience_tier_5,google_topics, andmarketing_itemsfor any custom categories built for you. A set with nothing in it can be left out, so treat each one as optional.smart_tagsis filled only if smart tags are enabled for your account.
Scores and relevances are strings, not numbers. Parse before you compare them.
If Neuwo could not analyse the page, the response carries an error message
rather than any of these blocks.
Choose what comes back
Your account has settings for what an answer carries. Five fields of
POST /GetAiTopics change them for a single call, and nothing is saved to your
account:
iab_content_versions: the IAB Content Taxonomy version,1.0,2.2,3.0or3.1. Repeat the field for more than one; each version then gets lists of its own, such asiab_content_3.1_tier_1.iab_audience_versions=1.1: the IAB Audience Taxonomy lists.google_topics=trueorfalse: thegoogle_topicslist.sentiment_3=trueorfalse: thesentiment_3object, see Sentiment.hierarchy=trueorfalse: theparentschains on each tag, the tag's place in Neuwo's topic tree.
curl -X POST "https://napi.neuwo.ai/api/aitopics/GetAiTopics?token=YOUR_AUTO_TAGGING_TOKEN" \
--data-urlencode "format=json" \
--data-urlencode "headline=Cats: The Perfect Companion for Modern Living" \
--data-urlencode "content=Cats make wonderful pets for modern households." \
--data-urlencode "iab_content_versions=3.1" \
--data-urlencode "sentiment_3=true" \
--data-urlencode "hierarchy=true"A field you leave out keeps your account's setting. The API reference describes each one, with an example answer.
Images
The Auto-Tagging API also classifies a picture. The address is the text
endpoint with /image at the end, the token is the same, and image_url takes
the place of content:
curl -X POST "https://napi.neuwo.ai/api/aitopics/GetAiTopics/image?token=YOUR_AUTO_TAGGING_TOKEN" \
-d "image_url=https://example.com/images/wildfire.jpg" \
-d "format=json"image_urlorimage_b64. A public address Neuwo fetches, or the bytes themselves base64-encoded, withimage_mimesuch asimage/jpeg. JPEG, PNG, WebP, GIF, BMP and TIFF up to 25 MB by URL, or about 15 MB as base64.contentandheadlinecan travel in the same call to classify a picture together with its story.- The answer is the same as for text. It carries the
tags,marketing_categories,brand_safetyandsmart_tagsblocks described under Read the response, as JSON or XML, with the settings of your token. The other fields of the text endpoint, such asformat,langandtag_limit, work here too. - Neuwo reads the picture on its own infrastructure and classifies what it is about with the same models as an article. No third party sees the picture.
- The score limits for IAB categories on pictures are set by Neuwo. The per-call IAB limits of the text endpoint do not apply to a picture.
- A picture that cannot be fetched or decoded answers
400. When the image service is temporarily unavailable, the answer is503: repeat the call shortly.
Sentiment
Neuwo can add a page-level sentiment to the answers of the Auto-Tagging API: whether the events a text reports are negative, neutral or positive, and how strongly. An obituary, an accident report or a match lost are negative; a product launch, an award or a match won are positive; reference, service and most factual news reporting are neutral, which is deliberately the wide default band.
It is a separate question from brand safety. An
accident report is negative and brand-safe at the same time, and brand_safety
keeps answering the safety question on its own.
- Ask for it per call, or have it on for every call.
sentiment_3=trueon aPOST /GetAiTopicsorPOST /GetAiTopics/imagecall adds it to that answer. Neuwo can also switch it on for your account, on request at adops@neuwo.ai, so that every answer carries it;sentiment_3=falsethen leaves it out of a single call. A call without the field, on an account where it is not switched on, is unchanged: the field is left out, never sent asnull. - The object is the same on every endpoint. It comes under the key
sentiment_3, which names the kind of sentiment: three categories with a score.labelisnegative,neutralorpositive.scoreis a number from-1to1with two decimals, the strength of that valence rather than a confidence. labelis a band ofscore. Neutral is a deliberately wide band in the middle of the scale. If you want a narrower or wider neutral band, cut onscoreyourself.- Sentiment is computed when a text is analysed. A text that Neuwo
analysed before sentiment was available can come back from its cache without
the field for up to two days; a fresh analysis carries it. Treat a missing
sentiment_3as not computed, never as neutral.
Where it appears:
POST /GetAiTopicswithformat=json: asentiment_3object as the last key of the response.POST /GetAiTopicsas XML: two elements at the end,sentiment_3_labelandsentiment_3_score. Without sentiment in the answer neither is sent.POST /GetAiTopics/image: the same asPOST /GetAiTopics, in JSON and in XML.POST /GetCustomTopics: the same object aftertags, or the same two elements in XML, on accounts where Neuwo has switched sentiment on; this endpoint has nosentiment_3field.
The call is the one under Make your first call, with
sentiment_3=true added; on an account where sentiment is switched on, the field
can be left out. A routine piece of local news:
curl -X POST "https://napi.neuwo.ai/api/aitopics/GetAiTopics?token=YOUR_AUTO_TAGGING_TOKEN" \
--data-urlencode "format=json" \
--data-urlencode "headline=Council approves next year's road maintenance budget" \
--data-urlencode "content=The city council approved next year's road maintenance budget on Tuesday. Resurfacing of the main street begins in May and is expected to take four months, with traffic diverted along the ring road during the work. Residents can follow the schedule on the city's website." \
--data-urlencode "sentiment_3=true"With sentiment in the answer, it ends with the new object. Trimmed to the blocks you already know:
{
"tags": [ … ],
"brand_safety": { "BS_score": "1.0", "BS_indication": "yes" },
"marketing_categories": { … },
"smart_tags": [],
"sentiment_3": {
"label": "neutral",
"score": 0.04
}
}scoreis a number, unlike the scores and relevances above it, which are strings.- A score of
0.04sits inside the neutral band: a factual report with no loss or gain in it. A strongly negative report scores towards-1, a celebratory one towards1.
The same answer as XML ends with the two elements before the closing tag:
<rsp version="1.0">
…
<sentiment_3_label>neutral</sentiment_3_label>
<sentiment_3_score>0.04</sentiment_3_score>
</rsp>Reference
Every endpoint, parameter and response, with a request builder.
SDKs
Per-endpoint code samples for each SDK are shown inside the reference next to the endpoint they belong to. These pages cover installation, authentication and a full walkthrough.
Moving from the previous address
An integration built against https://m1api.neuwo.ai moves to
https://napi.neuwo.ai by changing its base URL. The token, the paths and the
response are the same. What changes, and how to move.