@ttab/api-client
Advanced tools
Browser-friendly TypeScript/JavaScript client for TT Nyhetsbyrån public APIs.
Browser-friendly TypeScript client for TT Nyhetsbyrån public APIs. The client code (and this README file) has been automatically generated from the API definition located at https://api.tt.se/docs.
Instructions for building the client are here.
To access the APIs you need to have a registered user account at TT Nyhetsbyrån.
The API uses OAuth2 token authentication. To be able to generate an OAuth2 token you will need a OAuth2 client registered with TT Nyhetsbyrån. If you don't have one, please contact support@tt.se.
The OAuth2 endpoints are documented
here. In short, to obtain a token
you call the https://tt.se/o/oauth2/token endpoint like this:
curl -XPOST -d username="<USERNAME>" \
-d password="<PASSWORD>" \
-d grant_type=password \
-d scope="roles" \
-d client_id="<CLIENT_ID>" \
-d client_secret="<CLIENT_SECRET>" \
https://tt.se/o/oauth2/token
You will get a JSON payload back. One of the properties is called access_token
and contains the the OAuth2 token you need to connect to the API. To run the
examples below it is handy to have this token exported as an environment
variable:
export TOKEN="a.DV_8caPCk7CVQs_jr4_MpqZSxj4e25N3GbTEGXk2w4MUwzB..."
Searching the database for matching items is a common operation. You supply the
mediaType (image, text, video, etc.) and an object with query
parameters, and get a result object with an array of search hits.
This is a basic query, looking for panda pictures:
import { Api } from "@ttab/api-client";
let api = new Api({ token: process.env.TOKEN || "" });
api.content.search("image", { q: "panda" }).then(res => {
res.hits.forEach(hit => {
console.log(hit.uri, hit.product);
});
});
The search result is restricted to only match items allowed by the customer
agreements linked to your user account. If you wish to further restrict the
search result to match a given agreement you can use the agr parameter:
api.content.search("image", { q: "panda", agr: [20031] }).then(res => {
res.hits.forEach(hit => {
console.log(hit.uri, hit.product);
});
});
You can also restrict the search result to only contain items matching one or more product codes:
api.content
.search("image", { q: "panda", p: ["FOGNRE", "FOGNREEJ"] })
.then(res => {
res.hits.forEach(hit => {
console.log(hit.uri, hit.product);
});
});
While the api.content.search() method only returns items that are already present in the database, api.content.stream() provides a way to get a near real-time stream of new items as they are being indexed.
The api.content.stream() method accepts roughly the same arguments as api.content.search(), with the exception of arguments that affect time ranges and result pagination. They don't make any sense while streaming data, as we will always return the latest items added.
api.content.stream() also accepts two additional
parameters. wait is the maximum time (in seconds) to wait for new items before
the call returns with an empty result. last is the uri of the last item that
the client received. The idea is that if items has been added to the database
since the client received the last result, the call will return immediately with
those new items.
Utilizing the last parameter you can write a simple loop like this, that
prints the uri, source and headline for each new image as it is added to the
database:
import { Api } from "@ttab/api-client";
let api = new Api({ token: process.env.TOKEN || "" });
function loop(last?: string) {
return api.content.stream("image", { last: last }).then(result => {
let _last = null;
result.hits.forEach(hit => {
console.log(hit.uri, hit.source, hit.headline);
_last = hit.uri;
});
return loop(_last);
});
}
loop().catch(err => {
console.error(err);
});
While you can handle stream loops yourself, the API client supplies a utility class to make content streaming easier.
constructor(api, mediaType, parameters) -
api - an Api instancemediaType and parameters - the same arguments accepted by
api.content.stream()stop() - request that the content stream be stopped. When the stream has
closed down and no more data events can be expected a final close event
will be emitted.data - emitted once for every hit.error - emitted on error. It is up to the user to decide how to handle this
error and if/when to close the content stream.close - emitted when the content stream is closed. No more data events
will be emitted.The following code is equivalent to the loop in the previous section. It prints
the uri, source and headline for each new image as it is added to the
database. It handles errors by printing a stack trace and closing down the
stream.
import { Api, ContentStream } from "@ttab/api-client";
let api = new Api({ token: process.env.TOKEN || "" });
let stream = new ContentStream(api, "image", {});
stream.on("data", hit => {
console.log(hit.uri, hit.source, hit.headline);
});
stream.on("error", err => {
console.log("err", err);
stream.close();
});
stream.on("close", () => {
console.log("closed");
});
Searching the TT archives.
"_all" | "image" | "video" | "graphic" | "text" | "feature" | "page" | "planning" | "calendar" -
Only return items of this media type.q?: string - A query string used for free text searching.p?: Array<string> - A list of product codes. Only items matching at least
one of these codes will be returned. The list of current product codes is
here.agr?: Array<number> - A list of customer agreement IDs belonging to the
current user. Only items covered by at least one of there agreements will be
returned.tr?: "h" | "d" | "w" | "m" | "y" - Time range: last hour, day, week,
month, or year.trs?: string - Start datetre?: string - End dates?: number - Size of search result.fr?: number - Index into the search result. Used for pagination.api.content
.search("image", {
q: "panda",
p: ["FOGNRE", "FOGNREEJ"],
agr: [20031, 20035],
tr: "w"
})
.then(result => {
// do something with result
});
Realtime delivery of content.
Long poll call that will wait for a specified time period (default: 60s, max
300s) until a matching item is published. The parameters are similar to those
for search, with the exception that time ranges and pagination doesn't make
sense in this context (we will always return the most recent item).
"_all" | "image" | "video" | "graphic" | "text" | "feature" | "page" | "planning" | "calendar" -
Only return items of this media type.q?: string - A query string used for free text searching.p?: Array<string> - A list of product codes. Only items matching at least
one of these codes will be returned. The list of current product codes is
here.agr?: Array<number> - A list of customer agreement IDs belonging to the
current user. Only items covered by at least one of there agreements will be
returned.last?: string - The uri of the last item received.wait?: number - The time (in seconds) to wait for updates before returning
an empty result.api.content
.stream("image", {
q: "panda",
p: ["FOGNRE", "FOGNREEJ"],
agr: [20031, 20035]
})
.then(result => {
// do something with result
});
List all notifications
"_all" | "image" | "video" | "graphic" | "text" | "feature" | "page" | "planning" | "calendar" -
Only return items of this media type.api.content.getNotifications("image").then(result => {
// do something with result
});
Create a new mobile notification
"_all" | "image" | "video" | "graphic" | "text" | "feature" | "page" | "planning" | "calendar" -
Only return items of this media type.q?: string - A query string used for free text searching.p?: Array<string> - A list of product codes. Only items matching at least
one of these codes will be returned. The list of current product codes is
here.agr?: Array<number> - A list of customer agreement IDs belonging to the
current user. Only items covered by at least one of there agreements will be
returned.title: string -api.content
.addNotificationMobile("image", {
q: "panda",
p: ["FOGNRE", "FOGNREEJ"],
agr: [20031, 20035],
title: "my mobile notification"
})
.then(result => {
// do something with result
});
Create a new email notification
"_all" | "image" | "video" | "graphic" | "text" | "feature" | "page" | "planning" | "calendar" -
Only return items of this media type.q?: string - A query string used for free text searching.p?: Array<string> - A list of product codes. Only items matching at least
one of these codes will be returned. The list of current product codes is
here.agr?: Array<number> - A list of customer agreement IDs belonging to the
current user. Only items covered by at least one of there agreements will be
returned.title: string -email: string - The email address to send emails to.api.content
.addNotificationEmail("image", {
q: "panda",
p: ["FOGNRE", "FOGNREEJ"],
agr: [20031, 20035],
title: "my email notification",
email: "my.email@address.com"
})
.then(result => {
// do something with result
});
Remove an existing notification
"_all" | "image" | "video" | "graphic" | "text" | "feature" | "page" | "planning" | "calendar" -
Only return items of this media type.string - An UUID string.api.content.removeNotification("image", "123").then(result => {
// do something with result
});
Get the current customer agreements.
Return a list of applicable customer agreements for the current user.
api.user.getAgreements().then(result => {
// do something with result
});
Get the profile for the current user.
The user profile is an unstructured JSON object containing non-secret application data (settings and such). Web applications are free to access this information as they see fit.
api.user.getProfile().then(result => {
// do something with result
});
Update the profile for the current user.
Replaces the entire user profile with the object passed in the request body.
For more controlled updates of the user profile, use the
PUT /user/v1/profile/{property} endpoint.
{ }api.user.updateProfile({ property1: "customValue" }).then(result => {
// do something with result
});
Get selected properties of the profile for the current user.
The user profile is an unstructured JSON object containing non-secret application data (settings and such). Web applications are free to access this information as they see fit. Often, applications are not interested in the whole user profile. This endpoint returns only selected properties.
Array<string> - A list of property names.api.user.getProfileByProperty(["property1", "property2"]).then(result => {
// do something with result
});
Update selected properties of the profile for the current user.
Replaces selected properties, but doesn't modify the rest of the user profile.
This is a more controlled version of the PUT /user/v1/profile endpoint.
Given a profile object like
{
"property1": { ... },
"property2": { ... },
...
}
and a property parameter like property1,property2, this endpoint will update
the given properties, but leave the rest of the user profile intact. Properties
present in profile but not listed in property will not be written.
Conversely, properties listed in property but not present in profile will
not be overwritten with null.
Array<string> - A list of property names.{ }api.user
.updateProfileByProperty(["property1", "property2"], {
property1: "customValue"
})
.then(result => {
// do something with result
});
Register a new mobile device.
string -type: "ios" | "ios-sandbox" | "android" - The type of device:
ios (for the production environment)ios-sandbox (for the APN sandbox)androidname?: string - The name of this mobile device.model: string - The model of this mobile device.api.user
.updateDevice(
"5a21a38a24857b344c66aadade0abf2a748fcacf2ddf466e83e4fcd1cefab66a",
{ type: "ios", name: "my iPhone", model: "iPhone 8" }
)
.then(result => {
// do something with result
});
Unregister a mobile device.
string -api.user
.removeDevice(
"5a21a38a24857b344c66aadade0abf2a748fcacf2ddf466e83e4fcd1cefab66a"
)
.then(result => {
// do something with result
});
List all collections
Returns a list of all collections belonging to the current user.
api.collection.getCollections().then(result => {
// do something with result
});
Create a new collection.
Creates an new named collection for the current user. This operation is
asynchronous, and there may be a delay before the change is visible using the
GET /collection/v1/collection endpoint.
{ 'name': string;}api.collection.addCollection({ name: "my collection" }).then(result => {
// do something with result
});
Get collection properties and contents
Returns all properties and contents of a single collection.
string - ID of a collection.api.collection.getCollection("123").then(result => {
// do something with result
});
Update collection properties
Updates an existing collection belonging to the current user. This operation is
asynchronous, and there may be a delay before the change is visible using the
GET /collection/v1/collection endpoint.
string - ID of a collection.{ 'name': string;}api.collection
.updateCollection("123", { name: "my collection" })
.then(result => {
// do something with result
});
Remove an existing collection
Removes an existing collection belonging to the current user. This operation is
asynchronous, and there may be a delay before the change is visible using the
GET /collection/v1/collection endpoint.
string - ID of a collection.api.collection.removeCollection("123").then(result => {
// do something with result
});
Add items to collection
Adds any number of items to a given collection belonging to the current user.
The items must exist in the content database and be visible for the user. If
not, this call will still return successfully, but the collection remain
unchanged. This operation is asynchronous, and there may be a delay before
changes are visible using the GET /collection/v1/collection/{id} endpoint.
string - ID of a collection.Array<{ 'uri': string;}>api.collection
.addCollectionItems("123", [{ uri: "http://tt.se/media/image/sdltd8f4d87" }])
.then(result => {
// do something with result
});
Remove items from collection
Removes any number of items from a given collection belonging to the current
user. If one or more items do not currently belong to the collection, this call
will still return successfully, but those items will be ignored. This operation
is asynchronous, and there may be a delay before changes are visible using the
GET /collection/v1/collection/{id} endpoint.
string - ID of a collection.Array<{ 'uri': string;}>api.collection
.removeCollectionItems("123", [
{ uri: "http://tt.se/media/image/sdltd8f4d87" }
])
.then(result => {
// do something with result
});
interface ttninjs {
uri: string;
type?:
| "text"
| "audio"
| "video"
| "picture"
| "graphic"
| "composite"
| "planning"
| "component"
| "event";
mimetype?: string;
representationtype?: "complete" | "incomplete" | "associated";
profile?: "PUBL" | "DATA" | "INFO" | "RAW";
version?: string;
versioncreated?: string;
versionstored?: string;
embargoed?: string;
date?: string;
datetime?: string;
enddate?: string;
enddatetime?: string;
embargoedreason?: string;
job?: string;
pubstatus?: "usable" | "withheld" | "canceled" | "replaced" | "commissioned";
copyrightholder?: string;
copyrightnotice?: string;
language?: string;
week?: number;
urgency?: number;
webprio?: number;
source?: string;
commissioncode?: string;
description_text?: string;
description_usage?: string;
usageterms?: string;
body_text?: string;
body_html5?: string;
body_event?: {
arena?: string;
city?: string;
address?: string;
country?: string;
eventurl?: string;
eventphone?: string;
eventweb?: string;
organizer?: string;
organizerurl?: string;
organizerphone?: string;
organizermail?: string;
eventstatus?: string;
eventstatus_text?: string;
region?: string;
region_text?: string;
municipality?: string;
municipality_text?: string;
eventtags?: string;
eventtype?: string;
eventtype_text?: string;
note_extra?: string;
note_pm?: string;
accreditation?: string;
extraurl?: string;
createddate?: string;
createdby?: string;
changeddate?: string;
changedby?: string;
courtcasenumber?: string;
};
body_sportsml?: string;
body_pages?: {};
commissionedby?: Array<string>;
charcount?: number;
originaltransmissionreference?: string;
signals?: {
pageproduct?: string;
multipagecount?: number;
paginae?: Array<string>;
pagecode?: string;
pagevariant?: string;
};
product?: Array<{ [key: string]: {} }>;
person?: Array<{ [key: string]: {} }>;
organisation?: Array<{ [key: string]: {} }>;
place?: Array<{ [key: string]: {} }>;
subject?: Array<{ [key: string]: {} }>;
event?: Array<{ [key: string]: {} }>;
object?: Array<{ [key: string]: {} }>;
byline?: string;
bylines?: Array<{
byline?: string;
firstname?: string;
lastname?: string;
role?: string;
email?: string;
jobtitle?: string;
internal?: string;
phone?: string;
initials?: string;
affiliation?: string;
}>;
headline?: string;
slug?: string;
located?: string;
renditions?: {};
replacing?: Array<string>;
replacedby?: string;
associations?: {};
revisions?: Array<{ [key: string]: {} }>;
sector?: "INR" | "UTR" | "EKO" | "KLT" | "SPT" | "PRM";
}
interface agreement {
id?: number;
description?: {};
type?: "Subscription" | "Direct" | "Normal" | "Sketch";
products?: Array<product>;
}
interface collection {
id: string;
owner: string;
name: string;
colldate: string;
}
interface collectionItem {
id: string;
owner: string;
name: string;
colldate: string;
items: Array<ttninjs>;
}
interface product {
name?: string;
description?: {};
code?: string;
}
interface notification {
id: string;
title: string;
type: "mobile" | "email";
mediaType:
| "_all"
| "image"
| "video"
| "graphic"
| "text"
| "feature"
| "page"
| "planning"
| "calendar";
q?: string;
p?: Array<string>;
agr?: Array<number>;
}
FAQs
Browser-friendly TypeScript/JavaScript client for TT Nyhetsbyrån public APIs.
The npm package @ttab/api-client receives a total of 116 weekly downloads. As such, @ttab/api-client popularity was classified as not popular.
We found that @ttab/api-client demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 6 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Python 3.14 adds template strings, deferred annotations, and subinterpreters, plus free-threaded mode, an experimental JIT, and Sigstore verification.
Security News
Former RubyGems maintainers have launched The Gem Cooperative, a new community-run project aimed at rebuilding open governance in the Ruby ecosystem.
Security News
An opt-in lazy import keyword aims to speed up Python startups, especially CLIs, without the ecosystem-wide risks that sank PEP 690.