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'])
Was this section helpful?

What made this section unhelpful for you?

Add Workspace

Create new workspace based on latitude, longitude and radius. Title is also mandatory.

Maximum radius is 3000000m.

Header Parameters

Authorizationstring

Authorization token

Content-Typestring

Body Parameters

titlestring

string

positionobject

object

Show child attributes

radiusnumber

number (in meters) Minimum 30000

Response

201
Object
Created new workspace

Response Attributes

workspace_idinteger
errorboolean
400
Object

Response Attributes

workspace_idinteger
errorboolean
Was this section helpful?

What made this section unhelpful for you?

POST

/addCoordinates/

Select
1 2 3 4 5 6 7 8 9 10 11 curl --location 'https://osint.os-surveillance.io/api/addCoordinates/' \ --header 'Authorization: Bearer' \ --header 'Content-Type: application/json' \ --data '{ "title": "New York", "position": { "lat": 40.72020796700515, "lng": -74.0401684945897 }, "radius": 30000 }'

Response

{
  "workspace_id": 1,
  "error": false
}
Was this section helpful?

What made this section unhelpful for you?

Search

Run modules for given workspace and coordinates.

You must provide centre of your search and bounding box.

Bounding box must be inside of the bounding box as defined in Workspace.

Options parameter contains list of modules to run.

  • flickr
  • vkontakte

All modules are described in Modules section.

Possible error messages:

  • Please active your account.
  • Coordinates are not in the bounding box
  • Bounding box is not inside the workspace bounding box

Header Parameters

Authorizationstring
Content-Typestring

Body Parameters

optionsarray

Show child attributes

keywordsstring

Not used anymore

date_fromstring

Not used anymore

date_tostring

Not used anymore

coordinates_idnumber

workspace_id

latnumber

Center latitude

lngnumber

Center longitude

ne_latnumber
ne_lngnumber
sw_latnumber
sw_lngnumber
zoominteger

(Optional) zoom

Response

201
Object

Response Attributes

search_pknumber

ID of search request

blocked_modulesarray

List of blocked modules due to lack of credits

errorboolean
400
Object

Response Attributes

errorboolean
search_pkstring
blocked_modulesarray
messagestring
Was this section helpful?

What made this section unhelpful for you?

POST

/search/

Select
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 curl --location 'https://osint.os-surveillance.io/api/search/' \ --header 'Authorization: Bearer' \ --header 'Content-Type: application/json' \ --data '{ "options": [ "flickr", "vkontakte" ], "keywords": null, "date_from": null, "date_to": null, "coordinates_id": 1, "lat": 40.72695348506061, "lng": -73.99575186426779, "ne_lat": 40.81369273143631, "ne_lng": -73.15672826021006, "sw_lat": 40.605495194313995, "sw_lng": -74.56091832368662, "zoom": 15 }'

Response

{
  "search_pk": 31,
  "blocked_modules": [],
  "error": false
}
Was this section helpful?

What made this section unhelpful for you?

Get progress

Get progress of the running modules.

Header Parameters

Authorizationstring

Path Parameters

search_pkstring Required

The unique identifier of the task for which progress is being requested.

Response

200
Object

Response Attributes

completednumber
totalnumber
progressnumber
404
Object

Response Attributes

errorboolean
Was this section helpful?

What made this section unhelpful for you?

GET

/getProgress/{search_pk}/

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

Response

{
  "completed": 3,
  "total": 14,
  "progress": 21.428571428571427
}
Was this section helpful?

What made this section unhelpful for you?

Get search results

Get search results after all or some modules finished

Header Parameters

Authorizationstring

Path Parameters

search_pkstring Required

The unique identifier for the search request that was made in order to retrieve the search results.

Response

200
Object

Response Attributes

typestring
objectsarray

Show child attributes

Was this section helpful?

What made this section unhelpful for you?

GET

/getSearchResults/{search_pk}/

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

Response

[
  {
    "type": "flickr",
    "objects": [
      {
        "id": 1001,
        "location": {
          "lat": 38.652979,
          "lng": -90.543491
        },
        "person": [],
        "date_created": "2024-04-10T17:30:13.705414Z",
        "notes": "",
        "url": "https://flickr.com/photos/51035555243@N01/53355907945/",
        "is_favorite": false,
        "title": "Barack Obama Elementary School",
        "photo_id": "53355907945",
        "user_id": "51035555243@N01",
        "photo_url": "https://live.staticflickr.com/65535/53355907945_06ef423980_n.jpg",
        "timestamp": "2014-08-22T08:56:34",
        "coordinates": 11,
        "search_request": 36,
        "type": "flickr"
      },
      {
        "id": 528,
        "location": {
          "lat": 38.652979,
          "lng": -90.543491
        },
        "person": [],
        "date_created": "2024-04-10T17:44:15.252128Z",
        "notes": "",
        "url": "https://vk.com/id445558837?z=photo445558837_457239108",
        "is_favorite": false,
        "owner_id": "445558837",
        "photo_url": "https://sun9-5.userapi.com/impg/c856124/v856124951/1d4a89/RjSOMbb6J5E.jpg?size=810x1080&quality=96&sign=2b6a5f336aff30dccb079a46db5c7141&c_uniq_tag=EEVVc6KKBZBmjbdiffkVqKdOc0vrlOdMk911R-BbUUE&type=album",
        "photo_id": "457239108",
        "text": "",
        "timestamp": "2020-01-22T16:48:45Z",
        "coordinates": 11,
        "search_request": 36,
        "type": "vkontakte"
      }
    ]
  },
  {
    "type": "vkontakte",
    "objects": [
      {
        "id": 528,
        "location": {
          "lat": 38.652979,
          "lng": -90.543491
        },
        "person": [],
        "date_created": "2024-04-10T17:44:15.252128Z",
        "notes": "",
        "url": "https://vk.com/id445558837?z=photo445558837_457239108",
        "is_favorite": false,
        "owner_id": "445558837",
        "photo_url": "https://sun9-5.userapi.com/impg/c856124/v856124951/1d4a89/RjSOMbb6J5E.jpg?size=810x1080&quality=96&sign=2b6a5f336aff30dccb079a46db5c7141&c_uniq_tag=EEVVc6KKBZBmjbdiffkVqKdOc0vrlOdMk911R-BbUUE&type=album",
        "photo_id": "457239108",
        "text": "",
        "timestamp": "2020-01-22T16:48:45Z",
        "coordinates": 11,
        "search_request": 36,
        "type": "vkontakte"
      }
    ]
  }
]
Was this section helpful?

What made this section unhelpful for you?

Check errors

Some modules might not run properly, to find out which ones; endpoint checkErrors needs to be queried, after get progress returned all tasks as done.

Include previously obtained “search_pk”

Path Parameters

search_pkstring

Response

200
Object
List of modules that failed

Response Attributes

errorsarray
Was this section helpful?

What made this section unhelpful for you?

GET

/checkErrors/{search_pk}

Select
1 curl --location --globoff 'https://osint.os-surveillance.io/api/checkErrors/{search_pk}' \

Response

{
  "errors": []
}
Was this section helpful?

What made this section unhelpful for you?

Additional endpoints

Below endpoints provide additional features like get workspaces, user information, database search or querying particular item.

Was this section helpful?

What made this section unhelpful for you?

Search database

Search across all gathered items in database

Header Parameters

Content-Typestring

Body Parameters

querystring
person_or_itemstring
item_typearray

Show child attributes

workspace_idnumber

Workspace ID to search in

Response

200
Object

Response Attributes

resultsarray

Show child attributes

countnumber
workspace_idnumber
Was this section helpful?

What made this section unhelpful for you?

POST

/searchDatabase/

Select
1 2 3 4 5 6 7 8 9 10 11 12 curl --location 'https://osint.os-surveillance.io/api/searchDatabase/' \ --header 'Content-Type: application/json' \ --data '{ "query": "", "person_or_item": "item", "item_type": [ "flickr", "strava", "vkontakte" ], "workspace_id": 1 }'

Response

{
  "results": [
    {
      "id": 1458,
      "location": {
        "lat": 40.716395,
        "lng": -74.011256
      },
      "person": [],
      "date_created": "2024-04-11T14:15:00.824935Z",
      "notes": "",
      "url": "https://flickr.com/photos/xxx/",
      "is_favorite": false,
      "title": "Eyes that look   -   Ojos que miran",
      "photo_id": "xxxx",
      "user_id": "xxxx@N08",
      "photo_url": "https://live.staticflickr.com/xxx.jpg",
      "timestamp": "2019-12-25T20:08:45Z",
      "coordinates": 7,
      "search_request": 38,
      "type": "flickr"
    }
  ],
  "count": 1,
  "workspace_id": 7
}
Was this section helpful?

What made this section unhelpful for you?

Show all items

Show all items that belong to the given workspace

Path Parameters

workspace_idstring Required

The unique identifier for the resource to retrieve information for in the "Show all read" endpoint.

Response

200
Object

Response Attributes

typestring
objectsarray

Show child attributes

404
Object
400
Object

Response Attributes

errorboolean
Was this section helpful?

What made this section unhelpful for you?

GET

/showAll/{workspace_id}/

Select
1 curl --location --globoff 'https://osint.os-surveillance.io/api/showAll/{workspace_id}/' \

Response

[
  {
    "type": "flickr",
    "objects": [
      {
        "id": 1601,
        "location": {
          "lat": 40.724681,
          "lng": -74.001942
        },
        "person": [],
        "date_created": "2024-04-11T15:18:39.234048Z",
        "notes": "",
        "url": "https://flickr.com/photos/XXXXX/",
        "is_favorite": false,
        "title": "XXXXXXX",
        "photo_id": "XXXXXX",
        "user_id": "XXXXXX@N07",
        "photo_url": "https://live.staticflickr.com/XXXXXX.jpg",
        "timestamp": "2019-09-08T23:26:05Z",
        "coordinates": 1,
        "search_request": 39,
        "type": "flickr"
      }
    ]
  }
]
Was this section helpful?

What made this section unhelpful for you?

Remove Workspace

Remove workspace and associated items

Body Parameters

idnumber

Response

200
Object

Response Attributes

errorboolean
400
Object

Response Attributes

errorboolean
Was this section helpful?

What made this section unhelpful for you?

POST

/removeCoordinates/

Select
1 2 3 4 curl --location 'https://osint.os-surveillance.io/api/removeCoordinates/' \ --data '{ "id": 1 }'

Response

{
  "error": false
}
Was this section helpful?

What made this section unhelpful for you?

Get user info

Get information about current user and credits usage

Header Parameters

Authorizationstring
Content-Typestring

Response

200
Object

Response Attributes

idnumber
airbnb_requestsnumber
alltrails_requestsnumber
weather_requestsnumber
amber_alerts_requestsnumber
cameras_overpass_requestsnumber
crimes_requestsnumber
flickr_requestsnumber
instagram_requestsnumber
incidents_requestsnumber
planes_requestsnumber
shodan_requestsnumber
snapchat_requestsnumber
surveillance_cameras_requestsnumber
sportstracker_requestsnumber
strava_requestsnumber
traffic_cameras_requestsnumber
vessels_requestsnumber
vkontakte_requestsnumber
weibo_requestsnumber
wigle_requestsnumber
windy_requestsnumber
news_requestsnumber
worldcam_requestsnumber
youtube_requestsnumber
places_requestsnumber
wikiloc_requestsnumber
amtrak_requestsnumber
is_activeboolean
auth0_userstring
wigle_limitnumber
shodan_limitnumber
other_limitnumber
offenders_requestsnumber
ticketmaster_requestsnumber
zillow_requestsnumber
eventbrite_requestsnumber
craigslist_requestsnumber
meetup_requestsnumber
nextdoor_requestsnumber
username_requestsnumber
username_limitnumber
outdooractive_requestsnumber
waze_requestsnumber
ai_geolocate_requestsnumber
ai_geolocate_limitnumber
findpenguins_requestsnumber
bikemap_requestsnumber
facecheck_requestsnumber
facecheck_limitnumber
acled_requestsnumber
typestring
emailstring
Was this section helpful?

What made this section unhelpful for you?

GET

/getUserInfo/

Select
1 2 3 curl --location 'https://osint.os-surveillance.io/api/getUserInfo/' \ --header 'Authorization: Bearer' \ --header 'Content-Type: application/json'

Response

{
  "id": 1,
  "airbnb_requests": 4,
  "alltrails_requests": 6,
  "weather_requests": null,
  "amber_alerts_requests": 1,
  "cameras_overpass_requests": null,
  "crimes_requests": 5,
  "flickr_requests": 10,
  "instagram_requests": null,
  "incidents_requests": null,
  "planes_requests": null,
  "shodan_requests": null,
  "snapchat_requests": 5,
  "surveillance_cameras_requests": 3,
  "sportstracker_requests": 4,
  "strava_requests": 7,
  "traffic_cameras_requests": 2,
  "vessels_requests": null,
  "vkontakte_requests": 9,
  "weibo_requests": 2,
  "wigle_requests": null,
  "windy_requests": null,
  "news_requests": 4,
  "worldcam_requests": 2,
  "youtube_requests": 2,
  "places_requests": null,
  "wikiloc_requests": 6,
  "amtrak_requests": null,
  "is_active": true,
  "auth0_user": "auth0|659eee41a4ffcf97947a271a",
  "wigle_limit": 250,
  "shodan_limit": 125,
  "other_limit": 50,
  "offenders_requests": 2,
  "ticketmaster_requests": 1,
  "zillow_requests": 1,
  "eventbrite_requests": 1,
  "craigslist_requests": 1,
  "meetup_requests": 1,
  "nextdoor_requests": 1,
  "username_requests": null,
  "username_limit": 10,
  "outdooractive_requests": 3,
  "waze_requests": null,
  "ai_geolocate_requests": null,
  "ai_geolocate_limit": 10,
  "findpenguins_requests": 4,
  "bikemap_requests": 4,
  "facecheck_requests": 3,
  "facecheck_limit": 10,
  "acled_requests": 7,
  "type": "Unknown",
  "email": ""
}
Was this section helpful?

What made this section unhelpful for you?

Get items

Get items for given module and workspace

Header Parameters

Authorizationstring

Query Parameters

sortstring

latest, newest

pagestring

Current page

limitstring

Max 200

Path Parameters

workspace_idstring Required

The unique identifier of the item for which the coordinates are being retrieved.

item_typestring Required

The type of item for which the coordinates are being retrieved.

Response

200
Object

Response Attributes

resultsarray

Show child attributes

current_pagenumber
total_pagesnumber
total_resultsnumber
errorboolean
400
Object
Was this section helpful?

What made this section unhelpful for you?

GET

/getCoordinatesItems/{workspace_id}/{item_type}?sort=&page=1&limit=40

Select
1 2 curl --location --globoff 'https://osint.os-surveillance.io/api/getCoordinatesItems/{workspace_id}/{item_type}?page=1&limit=40' \ --header 'Authorization: Bearer' \

Response

{
  "results": [
    {
      "id": 1801,
      "location": {
        "lat": 49.256866,
        "lng": -123.120125
      },
      "person": [],
      "date_created": "2024-04-11T15:48:43.792712Z",
      "notes": "",
      "url": "https://flickr.com/XXX",
      "is_favorite": false,
      "title": "XXX",
      "photo_id": "XXX",
      "user_id": "XXX@N06",
      "photo_url": "https://live.staticflickr.com/XXXg",
      "timestamp": "2024-01-25T20:04:40Z",
      "coordinates": 12,
      "search_request": 40,
      "type": "flickr"
    }
  ],
  "current_page": 1,
  "total_pages": 10,
  "total_results": 400,
  "error": false
}
Was this section helpful?

What made this section unhelpful for you?

Get item

Gets item based on workspace id, module type and item id.

Path Parameters

workspace_idstring Required

The unique identifier for the workspace that contains the item.

item_typestring Required

The type of item for which coordinates are being retrieved.

item_idstring Required

The unique identifier for the item within the specified workspace.

Response

200
Object

Response Attributes

idnumber
locationobject

Show child attributes

personstring
date_createdstring
notesstring
urlstring
is_favoriteboolean
titlestring
photo_idstring
user_idstring
photo_urlstring
timestampstring
coordinatesnumber
search_requestnumber
typestring
peoplestring
facesarray
400
Object

Response Attributes

errorboolean
404
Object
Was this section helpful?

What made this section unhelpful for you?

GET

/getCoordinatesItem/{workspace_id}/{item_type}/{item_id}

Select
1 curl --location --globoff 'https://osint.os-surveillance.io/api/getCoordinatesItem/{workspace_id}/{item_type}/{item_id}' \

Response

{
  "id": 1804,
  "location": {
    "lat": 49.260116,
    "lng": -123.106595
  },
  "person": null,
  "date_created": "2024-04-11T15:48:43.793069Z",
  "notes": "",
  "url": "https://flickr.com/photos/95142644@N00/48683978726/",
  "is_favorite": false,
  "title": "Burnt house",
  "photo_id": "48683978726",
  "user_id": "95142644@N00",
  "photo_url": "https://live.staticflickr.com/65535/48683978726_ee1aedf8b8_n.jpg",
  "timestamp": "2019-06-09T13:41:14Z",
  "coordinates": 12,
  "search_request": 40,
  "type": "flickr",
  "people": null,
  "faces": []
}
Was this section helpful?

What made this section unhelpful for you?

Get Workspaces

Gets all workspaces associated with user.

Header Parameters

Authorizationstring

Response

200
Object
List of workspaces and associated coordinates

Response Attributes

citystring
east_latnumber
east_lngnumber
idnumber
latnumber

Center lat

lngnumber

Center lng

north_latnumber
north_lngnumber
south_latnumber
south_lngnumber
titlestring
west_latnumber
west_lngnumber
Was this section helpful?

What made this section unhelpful for you?

GET

/getCoordinates/

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

Response

[
  {
    "city": null,
    "east_lat": 49.263181497186295,
    "east_lng": -122.7116722875862,
    "id": 12,
    "lat": 49.263181497186295,
    "lng": -123.02863303127798,
    "north_lat": 49.470025466547604,
    "north_lng": -123.02863303127798,
    "south_lat": 49.05633752782499,
    "south_lng": -123.02863303127798,
    "title": "Vancouver",
    "west_lat": 49.263181497186295,
    "west_lng": -123.34559377496976
  },
  {
    "city": null,
    "east_lat": 51.817877849587795,
    "east_lng": 41.09446416304095,
    "id": 4,
    "lat": 51.817877849587795,
    "lng": 20.95963261152622,
    "north_lat": 64.26448887550302,
    "north_lng": 20.95963261152622,
    "south_lat": 39.37126682367256,
    "south_lng": 20.95963261152622,
    "title": "Europe",
    "west_lat": 51.817877849587795,
    "west_lng": 0.8248010600114881
  }
]
Was this section helpful?

What made this section unhelpful for you?

Hashtag monitoring

Search

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

based on hashtag