API Documentation

protect individuals ― expose phenomenon ― enable researchers

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:

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

(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 summary, enriched by semantic analysis, if available

Data Specifics

TBD

Request

https://facebook.tracking.exposed/api/v2/personal/thisisaworkingtokenusablewhenperformtest/enrich/

Response

TBD


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/persona/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

TBD…

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:

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