API explorerChangelog
API explorer
Changelog

Theme switcher

Open Source Surveillance API

This is documentation regarding Open Source Surveillance system - https://os-surveillance.io

Search

  • Social media
  • Events
  • Crimes
  • Critical Infrastructure
  • Public Cameras
  • Internet Exposed Devices
  • Wifi networks
  • Transportation system
  • News
  • and more

based on coordinates

Search

  • Telegram
  • Twitter
  • Instagram
  • Threads
  • Youtube
  • Tiktok

based on hashtag

Base URL

Production:

https://osint.os-surveillance.io/api

Language Box

Location

Below script

  • Creates new workspace with coordinates in New York by making request to /addCoordinates
  • Search Flickr and Vkontakte posts in provided coordinates and bounding box by making request to /search
  • Ask for task status by making request to /getProgress/{search_id}
  • Retrieve search results when it's ready by making request to /getSearchResults/{search_id}
PYTHON
import requests
import time
headers = {
"Authorization": "Bearer XXXX",
"Content-Type": "application/json"
}
BASE_URL = "https://osint.os-surveillance.io/api"
modules_to_run = ["flickr", "vkontakte"]
#Add new workspace to the database
def add_workspace():
  url = BASE_URL + "/addCoordinates/"

  

  payload = {

    "title": "New York",

    "position": {

      "lat": 40.72020796700515,

      "lng": -74.0401684945897

    },

    "radius": 30000

  }

  

  response = requests.post(url, headers=headers, json=payload)

  

  workspace_id = response.json()['workspace_id']

  

  return workspace_id
 
 
#Search for data in the workspace
#pass workspace_id from add_workspace()
#include latitude, longitude and bounding box of the area
def search(wokspace_id):
  url = BASE_URL + f"/search/"
  payload = {

      "options":

          modules_to_run,

      "keywords":None,

      "date_from":None,

      "date_to":None,

      "only_new":False,

      "coordinates_id":wokspace_id,

      "lat":40.71846412371451, # center latitude

      "lng":-73.99740740984262, # center longitude

      "ne_lat":40.74334880686837, # north east latitude

      "ne_lng":-73.81237074710944, # north east longitude

      "sw_lat":40.67945984569057, # south west latitude

      "sw_lng":-74.16341826297858 # south west longitude

  }

  

  response = requests.request("POST", url, headers=headers, json=payload)

  

  search_pk = response.json()['search_pk']

  

  return search_pk
#Check progress of the search request
  def get_progress(search_pk):
  url = BASE_URL + f"/getProgress/{search_pk}/"
  response = requests.request("GET", url, headers=headers)

  

  return response.json()
#Get results of the search request
def get_results(search_pk):
  url = BASE_URL + f"/getSearchResults/{search_pk}/"
  response = requests.request("GET", url, headers=headers)

  r_json = response.json()

  

  return response.json()
def check_errors():
  url = BASE_URL + "/checkErrors/"
  response = requests.request("GET", url, headers=headers)

  

  return response.json()['errors']
  pp = get_progress("21")
workspace_id = add_workspace()
search_pk = search(workspace_id) # next time when searching in this area, use same workspace_id
while True:
  progress = get_progress(search_pk)
  print(progress['progress'])
    if progress['progress'] == 100.0:
      results = get_results(search_pk)
      break
    else:
      time.sleep(1)
for result in results:
  for item in result['objects']:
    print(item)
    # print(item['title'])
    # print(item['timestamp'])
    # print(item['photo_url'])
    # print(item['location'])

Hashtag monitoring

Search

  • Telegram
  • Twitter
  • Instagram
  • Threads
  • Youtube
  • Tiktok

based on hashtag

Was this section helpful?

What made this section unhelpful for you?

Add Hashtag

Add new hashtag to monitor

Header Parameters

Authorizationstring
Content-Typestring

Body Parameters

hashtagstring

Hashtag to monitor

Response

200
Object
List of modules that failed

Response Attributes

errorsarray
messagestring
hashtag_idstring
Was this section helpful?

What made this section unhelpful for you?

POST

/addHashtag/

Select
1 2 3 4 5 6 curl --location 'https://osint.os-surveillance.io/api/addHashtag/' \ --header 'Authorization: Bearer' \ --header 'Content-Type: application/json' \ --data '{ "hashtag": "planecrash" }'

Response

{
  "errors": [],
  "message": "Hashtag added",
  "hashtag_id": "21"
}
Was this section helpful?

What made this section unhelpful for you?

Search

Search added hashtag by ID on different platforms.

Header Parameters

Authorizationstring
Content-Typestring

Body Parameters

hashtag_idstring
platformsarray

Platforms parameter takes list with ONLY ONE element - instagram or twitter or tiktok or telegram or threads or youtube

Show child attributes

Response

200
Object

Response Attributes

dataarray

Show child attributes

Was this section helpful?

What made this section unhelpful for you?

POST

/searchHashtag/

Select
1 2 3 4 5 6 7 8 9 curl --location 'https://osint.os-surveillance.io/api/searchHashtag/' \ --header 'Authorization: Bearer' \ --header 'Content-Type: application/json' \ --data '{ "hashtag_id": "16", "platforms": [ "twitter" ] }'

Response

{
  "data": [
    {
      "tweet_id": "1898065905592287334",
      "url": "https:/twitter.com/snklzoned/status/1898065905592287334",
      "text": "@RealAlexJones #zeudiners #GrandeFratello #JHOPE #Tommavi #ElonMusk #Trump #GrandeFratello #planecrash #LoveIslandAllStars #JHOPEDAY #LaCasaDeLosFamososCol2 #JHOPE #MFW",
      "source": null,
      "retweets": 1,
      "replies": null,
      "likes": null,
      "quotes": null,
      "views": null,
      "timestamp": "Fri Mar 07 17:39:10 +0000 2025",
      "photo_url": null,
      "person": {
        "user_id": null,
        "username": "snklzoned",
        "name": "Tfdson...",
        "url": "https://twitter.com/snklzoned",
        "photo_url": "https://pbs.twimg.com/profile_images/1684058514854150145/ZYamBI4C_normal.jpg",
        "description": "Two wrongs do not make a right but three lefts do. What do life and sex have in common.More you put in more you get out.\nGOD BLESS AMERICA. IFB ๐Ÿ‡บ๐Ÿ‡ฒ๐Ÿฆ…๐Ÿ—ฝ\nMAGA",
        "followers": 14469,
        "following": 14057,
        "timestamp": "Sun May 25 18:04:45 +0000 2014"
      }
    }
  ]
}
Was this section helpful?

What made this section unhelpful for you?

Get all Hashtags

Get all added hashtags and associated IDs

Header Parameters

Authorizationstring

Response

200
Object

Response Attributes

objectsarray

Show child attributes

Was this section helpful?

What made this section unhelpful for you?

GET

/getHashtags/

Select
1 2 curl --location 'https://osint.os-surveillance.io/api/getHashtags/' \ --header 'Authorization: Bearer' \

Response

{
  "objects": [
    {
      "id": 13,
      "name": "biden",
      "platform": [
        {
          "name": "telegram"
        },
        {
          "name": "youtube"
        },
        {
          "name": "tiktok"
        },
        {
          "name": "twitter"
        },
        {
          "name": "instagram"
        },
        {
          "name": "threads"
        },
        {
          "name": "twitter"
        }
      ],
      "timestamp": "2025-02-22T14:50:26.883975Z",
      "type": "hashtag"
    },
    {
      "id": 16,
      "name": "planecrash",
      "platform": [
        {
          "name": "twitter"
        }
      ],
      "timestamp": "2025-03-07T16:53:16.267034Z",
      "type": "hashtag"
    }
  ]
}
Was this section helpful?

What made this section unhelpful for you?

Get Hashtag posts by type

Get collected posts by platfom and ID

Example - /getHashtagPosts/twitter/16

Header Parameters

Authorizationstring

Path Parameters

hashtag_typestring
hashtag_idstring

Response

200
Object

Response Attributes

dataarray

Show child attributes

Was this section helpful?

What made this section unhelpful for you?

GET

/getHashtagPosts/{hashtag_type}/{hashtag_id}

Select
1 2 curl --location --globoff 'https://osint.os-surveillance.io/api/getHashtagPosts/{hashtag_type}/{hashtag_id}' \ --header 'Authorization: Bearer' \

Response

{
  "data": [
    {
      "url": "https:/twitter.com/snklzoned/status/1898066063532998830",
      "text": "@RealAlexJones #zeudiners #Tommavi #JHOPE #GrandeFratello #ุณูˆุฑูŠุง_ุงู„ุงู† #ุฑู…ุถุงู† #ูŠูˆู…_ุงู„ุฌู…ุนุฉ #4เธ›เนˆเธฒเธŠเน‰เธฒ #ํŠธ๋ ˆ์ €์˜_๋ด„์€_YELLOW #zelena #ElonMusk #Trump #GrandeFratello #planecrash #LoveIslandAllStars #JHOPEDAY #LaCasaDeLosFamososCol2 #JHOPE",
      "source": null,
      "replies": null,
      "quotes": null,
      "timestamp": "2025-03-07T17:39:48Z",
      "photo_url": null,
      "location": {
        "lat": null,
        "lng": null
      },
      "id": 81,
      "person": [
        {
          "user_id": null,
          "name": "Tfdson...",
          "description": "Two wrongs do not make a right but three lefts do. What do life and sex have in common.More you put in more you get out.\nGOD BLESS AMERICA. IFB ๐Ÿ‡บ๐Ÿ‡ฒ๐Ÿฆ…๐Ÿ—ฝ\nMAGA",
          "followers": 14469,
          "following": 14057,
          "timestamp": "2014-05-25T18:04:45Z",
          "associated_item": null,
          "photo_url": "https://pbs.twimg.com/profile_images/1684058514854150145/ZYamBI4C_normal.jpg",
          "url": "https://twitter.com/snklzoned",
          "id": 1787,
          "username": "snklzoned"
        }
      ],
      "type": "twitter"
    }
  ]
}
Was this section helpful?

What made this section unhelpful for you?