The API here documented are implemented in our AGPL3 code.
Shared concepts
The base URL to access our API is: https://facebook.tracking.exposed/api/v2/.
Paging
There are some variables you need to have to perform a successful HTTP GET.
The $paging variable defines the number of entries that are retrieved by the API, as well
as the number of entries to skip. Some examples of $paging are:
/3-0/- Get 3 items (minimum result) and skip 0 items/3-2/- Get 3 items and skip the most recent 2/5-3/- Get 5 items and skipping the most recent 3
If you call /2000-0 you will just get the 2000 most recent entries.
For example, if you call /200-50 at the end of a “Summary” query
/200-50- Get 200 items and skip the most recent 50
(It is capped, you can’t download all the data with just one query).
Personal API
userToken is an unique identifier for you Facebook user. It’s a 40-characters long hexadecimal string. You can retrieve it by clicking on “Your Data” when you open Facebook on the browser where you installed the fbtrex extension. In the URL bar you will find the string. Just copy-paste it.
Special token for tests
To help develpment, when you are lacking of a personal token, you can test the API using thisisaworkingtokenusablewhenperformtest in your API requests. The data returned are consistent and they belong to some of our non-personal profile.
| Name | Description | URL |
|---|---|---|
| Personal Summary | link | personal/$userToken/summary/$paging |
| Personal Stats | link | personal/$userToken/stats/$paging |
| Personal CSV | link | personal/$userToken/csv/$paging |
| Data Exporter | link | personal/$userToken/exporter/$paging |
| Delete your Data | link | personal/$userToken/remove/$paging |
Personal Summary
URL
https://facebook.tracking.exposed/api/v2/personal/$YOUR_TOKEN/summary/$AMOUNT-$SKIP
Description
Returns a summary of personal data of an user. $YOUR_TOKEN is your userToken, paging is defined by two integers, $AMOUNT is the number of entries you want to get, $SKIP is how many entries you want to skip.
Data Specifics
| Name | Description | Format | Example |
|---|---|---|---|
| impressionTime | Time in which the impression was collected/observed. | string | "2019-04-19T18:06:49.000Z" |
| impressionOrder | Order at which the impression appeared when scrolling the timeline. | integer | 41 |
| semanticId | Unique Id about the semantic content. Posts that share the same semanticId have the same text (and therefore the same semantic analysis, which is the list of topics), you can use the semanticId in the semantic query API. | string | "7cd2480750f1cdb23215da6da4186b30cbe2f424" |
| opengraph | Provides any available opengraph data for a single impression. Contains the type of link, the link itself, the name of the site, the title of the page and a text description. | nested | { "fblinktype": "external", "link": "https://elpais.com/internacional/2019/04/18/estados_unidos/1555592324_696739.html", "isValid": true, "siteName": "elpais.com", "title": "El informe sobre la trama rusa revela los intentos de Trump por torpedear la investigación", "description": "Estoy jodido, este es el final de mi presidencia , dijo el mandatario tras el nombramiento de un fiscal especial, según el documento de Robert S. Mueller, hecho público este jueves" } |
| user | Pseudonym for the user that is seeing/collecting the impression. | string | "gelato-salmon-strawberry" |
| timeline | Pseudonym for the timeline in which the impression appeared. | string | "pasta-nutella-cabbage" |
| publicationTime | Time at which the post was first published. | string | "2019-04-18T19:21:01.000Z" |
| postId | Unique ID for the post (not the impression!) | string | "10125221421413523523" |
| permaLink | Permanent link to the public post. | string | "/elpais/posts/10156260262981570" |
| fblinktype | Type of media. Can be posts, photos or videos. | string | "posts" |
| nature | Specifies whether it is a "sponsored" or an "organic" post. | string | "organic" |
| images | Provides two values: `count` and `captions`. Count returns an integer with the total number of images contained in the impression. Captions contains a list of texts that describe the image (the 'alt' text that appears when you mouseover an image on Facebook.) | nested | {"count":1,"captions":["Image may contain: one or more people and text"]} |
| displaySource | The full string displayed above the post. | string | "El País added a new photo." |
| source | The name of the post publisher. | string | "El País" |
| sourceLink | Link to the profile of the impression publisher. | string | "https://www.facebook.com/elpais/" |
| texts | List of texts for the impression. Contains translations but not comments. | nested | [ "\"Estoy jodido, este es el final de mi presidencia\". Es la frase que dijo Trump cuando Robert Mueller se puso a investigar su presunta conexión con Rusia. En sus conclusiones, el fiscal especial recoge esta cita y sus intentos por torpedear la investigación, pero no ve delito", "El informe sobre la trama rusa revela los intentos de Trump por torpedear la investigación", "Estoy jodido, este es el final de mi presidencia, dijo el mandatario tras el nombramiento de un fiscal especial, según el documento de Robert S. Mueller, hecho público este jueves" ] |
| textsize | Length of the text. | integer | 547 |
| LIKE | Number of like reactions. | integer | 29 |
| HAHA | Number of haha reactions. | integer | 8 |
| ANGRY | Number of angry reactions. | integer | 18 |
| SAD | Number of sad reactions. | integer | 0 |
| LOVE | Number of love reactions. | integer | 0 |
| WOW | Number of surprised reactions. | integer | 0 |
Request
https://facebook.tracking.exposed/api/v2/personal/thisisaworkingtokenusablewhenperformtest/summary/1-0
Response
[{
"impressionTime": "2019-04-19T18:06:49.000Z",
"impressionOrder": 41,
"semanticId": "7cd2480750f1cdb23215da6da4186b30cbe2f424",
"opengraph": {
"fblinktype": "external",
"link": "https://elpais.com/internacional/2019/04/18/estados_unidos/1555592324_696739.html",
"isValid": true,
"siteName": "elpais.com",
"title": "El informe sobre la trama rusa revela los intentos de Trump por torpedear la investigación",
"description": "Estoy jodido, este es el final de mi presidencia, dijo el mandatario tras el nombramiento de un fiscal especial, según el documento de Robert S. Mueller, hecho público este jueves"
},
"user": "taco-tuna-tomato",
"timeline": "pepper-flour-shitake",
"publicationTime": "2019-04-18T19:21:01.000Z",
"postId": "10125221421413523523",
"permaLink": "/elpais/posts/10156260262981570",
"fblinktype": "posts",
"nature": "organic",
"images": {
"count": 1,
"captions": []
},
"displaySource": "El País",
"source": "El País",
"sourceLink": "https://www.facebook.com/elpais/",
"texts": [
"\"Estoy jodido, este es el final de mi presidencia\". Es la frase que dijo Trump cuando Robert Mueller se puso a investigar su presunta conexión con Rusia. En sus conclusiones, el fiscal especial recoge esta cita y sus intentos por torpedear la investigación, pero no ve delito",
"El informe sobre la trama rusa revela los intentos de Trump por torpedear la investigación",
"Estoy jodido, este es el final de mi presidencia , dijo el mandatario tras el nombramiento de un fiscal especial, según el documento de Robert S. Mueller, hecho público este jueves"
],
"textsize": 547,
"LIKE": 29,
"ANGRY": 18,
"HAHA": 8
},
{}]
Personal Stats
URL
https://facebook.tracking.exposed/api/v2/personal/$YOUR_TOKEN/stats/$AMOUNT-$SKIP
Description
Returns a list of timelines for the user, including a count for the number of impression and all the data contained in summary.
$YOUR_TOKEN is your userToken, paging is defined by two integers, $AMOUNT is the number of entries you want to get, $SKIP is how many entries you want to skip.
Data Specifics
| Name | Description | Format | Example |
|---|---|---|---|
| storedTimelines | Number of total timelines for the user. | integer | 1045 |
| served | Specifies the values for paging with which the API was called. | integer | { "amount": 1, "skip": 1 } |
| content | Contains a list of posts, with the startTime of the timeline, the country of the user, the impressionOrder, impressionTime, htmlId and timelineId, as well as a summary with the same information as the "summary" API. | { "startTime": "2019-05-02T08:33:40.000Z", "geoip": "ES", "impressionOrder": 1, "impressionTime": "2019-05-02T08:33:40.000Z", "htmlId": "xxx", "timelineId": "yyy", "summary": [] }, {...} | |
| timelines | List of timeline IDs with the number of impressions collected per ID. | { "timelinexxxxyyyy": 12, "timelineyyyyyyyzzzzzz" 65 |
Request
https://facebook.tracking.exposed/api/v2/personal/userToken/stats/1-0
Response
{
"storedTimelines": 31,
"served": {
"amount": 1,
"skip": 1
},
"content": [
{
"startTime": "2019-05-02T08:33:40.000Z",
"geoip": "UK",
"impressionOrder": 1,
"impressionTime": "2019-05-02T08:33:40.000Z",
"htmlId": "83489349sdfsfas907395923502352332",
"timelineId": "ac11229201721912aa129128192aa",
"summary": []
},
{
"startTime": "2019-05-02T08:33:40.000Z",
"geoip": "UK",
"impressionOrder": 2,
"impressionTime": "2019-05-02T08:33:40.000Z",
"htmlId": "83489349sdfsfas907395923502352332",
"timelineId": "ac11229201721912aa129128192aa",
"summary": []
}
],
"timelines": {
"ac11229201721912aa129128192aa": 12
}
}
Personal CSV
URL
https://facebook.tracking.exposed/api/v2/personal/$YOUR_TOKEN/csv/$AMOUNT-$SKIP
Description
Returns a comma-separated-values file containing personal data of an user. $YOUR_TOKEN is your userToken. Paging is defined by two integers, $AMOUNT is the number of entries you want to get, $SKIP is how many entries you want to skip.
Data Specifics
| Name | Description | Format | Example |
|---|---|---|---|
| nature | Specifies whether it is a "sponsored" or an "organic" post. | string | "organic" |
| publicationTime | Time at which the post was first published. | string | "2019-04-18T17:21:30.000Z" |
| postId | Unique ID for the post (not the impression!) | string | "1247146142126177" |
| permaLink | Permanent link to the public post. | string | "/CatalunyaDiari/posts/1247146142126177" |
| fblinktype | Type of media. Can be posts, photos or videos. | string | "posts" |
| source | The name of the post publisher. | string | "Catalunya Diari" |
| sourceLink | Link to the profile of the impression publisher. | string | "https://www.facebook.com/CatalunyaDiari/" |
| displaySource | The full string displayed above the post. | string | "Catalunya Diari" |
| textsize | Length of the text. | integer | 171 |
| texts | List of texts for the impression. Contains translations but not comments. | nested | [ "Hello world.", "Also this." ] |
| impressionTime | Time in which the impression was collected/observed. | string | "2019-04-21T15:05:15.000Z" |
| impressionOrder | Order at which the impression appeared when scrolling the timeline. | integer | 14 |
| user | Pseudonym for the user that is seeing/collecting the impression. | string | "goulash-nocilla-cucumber" |
| timeline | Pseudonym for the timeline in which the impression appeared. | string | "onion-couscous-strawberry" |
| semanticId | Unique Id for the impression collected, it's the same in other API feeds such as "semantic". | string | "82a416a63569d1b65ddfae1ff5b5812b13a247cf" |
Request
https://facebook.tracking.exposed/api/v2/personal/thisisaworkingtokenusablewhenperformtest/csv/1-0
Response, in CSV format:
"nature","publicationTime","postId","permaLink","fblinktype","source","sourceLink","displaySource","textsize","texts","impressionTime","impressionOrder","user","timeline","semanticId"
"organic","2019-04-18T17:21:30.000Z","1247146142126177","/CatalunyaDiari/posts/1247146142126177","posts","Catalunya Diari","https://www.facebook.com/CatalunyaDiari/","Catalunya Diari","171"," ‖▩‖ ","2019-04-21T15:05:15.000Z","14","goulash-nocilla-cucumber","onion-couscous-strawberry","82a416a63569d1b65ddfae1ff5b5812b13a247cf"
Your Enriched data
URL
https://facebook.tracking.exposed/api/v2/personal/$YOUR_TOKEN/enrich/$PAGING
Returns the metadata, stripped of few fields, enriched by semantic analysis, if available.
Data Specifics
TBD
Request
https://facebook.tracking.exposed/api/v2/personal/thisisaworkingtokenusablewhenperformtest/enrich/
Response
It is the content fetched why reality-check when load a timeline.
Export your Data
URL
https://facebook.tracking.exposed/api/v2/personal/$YOUR_TOKEN/exporter/$PAGING
Description
Returns all the data you own on our platform. $YOUR_TOKEN is your userToken.
Data Specifics
TBD
Request
`https://facebook.tracking.exposed/api/v2/personal/thisisaworkingtokenusablewhenperformtest/exporter/`
Response
TBD
Delete your Data
URL
https://facebook.tracking.exposed/api/v2/personal/$YOUR_TOKEN/remove/$PAGING
Description
Removes the data you own on our platform. $YOUR_TOKEN is your userToken. The output will confirm that your data has been deleted.
Data Specifics
TBD
Request
https://facebook.tracking.exposed/api/v2/personal/thisisaworkingtokenusablewhenperformtest/remove/5
Response
{"timelines":5,"impressions":63,"htmls":35,"summaries":35}
Daily aggregated Statistics
URL
https://facebook.tracking.exposed/api/v2/personal/$YOUR_TOKEN/daily/$PAGING
Description
Aggregated daily statistics on individual usage. It is used by Reality Check at the first visualization.
Data Specifics
Request
https://facebook.tracking.exposed/api/v2/personal/thisisaworkingtokenusablewhenperformtest/daily/0-3
Response
{
'dayamount': 'by default 3, is the amount of day looked at',
'skipped': 'by default 0, number of day skipped before pick the amount requested',
'stats': 'actual json data with the few info used to paint pie charts',
'pseudo': 'supporter pseudonym',
}
Node API
These APIs are not personal, they do not require $userToken and they can be queried by anyone. These API should not contain any information which might help an observer to spot who is the supporter using fbtrex.
TODO: complete this list, give a look to the implementation.
| Name | Description | URL |
|---|---|---|
| General Statistics | link | statistics/counter |
This API is meant for public statistics. They are aggregated and/or anonymized.
General Statistics
URL
https://facebook.tracking.exposed/api/v2/statistics/counter
Description
General statistics on facebook.tracking.exposed. Contains global and last week’s information. Please note that the fields that terminate in _lw are for last week.
Data Specifics
This API take as input all the database collections, and simply count the amount of objects contained.
for example: impressions produced two fields:
- impressions: it is the count of objects in the whole collection. all the impressions collected in the system
- impressions lw: stands for Last Week, it is the it is the count of the impression recorded in the last 7 days.
Request
https://facebook.tracking.exposed/api/v2/statistics/counter
Response
{
"content":
{
"impressions":15614360,
"impressions_lw":162084,
"aggregated":2673,
"aggregated_lw":140,
"labels":87946,
"labels_lw":87946,
"semantics":625307,
"semantics_lw":625307,
"anomalies":0,
"anomalies_lw":0,
"summary":1741653,
"summary_lw":89911,
"errors":52708,
"errors_lw":52708,
"metadata":1747629,
"metadata_lw":89938,
"htmls":9767659,
"htmls_lw":110072,
"accesses":215408,
"accesses_lw":974,
"timelines":1207216,
"timelines_lw":12826,
"supporters":3486,
"supporters_lw":13
},
"computedt":"2019-04-23T13:53:34.254Z",
"next":"2019-04-23T13:55:34.254Z",
"cacheTimeSeconds":120
}
Semantic Query APIs
Initially specified here: https://github.com/tracking-exposed/facebook/issues/128 then extended with this: https://github.com/tracking-exposed/facebook/commit/05502bb7817860495c08f5876c184d55da8c9785