TgScan API Documentation

API Authentication

To be able to query API on behalf of your user account you need to use API key. Use HTTP header "Api-Key: XXX" where XXX is your API key.

You can generate API key on https://tgdev.io/tgscan/api page. Only one API key per user account is allowed. When you generate new API key the old API key is removed (if it exists). Please remember API key when you see it first time. It is allowed to see API key only once. If you forget API key you'll need to generate new key.

API Key Security

You need to store your API key in secure location. Do not share it with people you do not trust. If you expose your API key you may loose all credits on your balance if third party will use your key to send requests to TgScan API.

Result of Failed API Request

Non-successful API results look like:

{
  "status": "error",
  "result": {
    "message": <str>
  }
}

The field ".result.message" contains short error description.

Result of Successful API Request

Successful API results look like:

{
  "status": "ok",
  "result": <struct>
}

The field ".result"contains result data. Structure of result data depends on API method you have called.

User's Groups Search Method

URL: https://api.tgdev.io/tgscan/v1/search

Required arguments:

  • query - must be a username (without "@") or Telegram numeric ID

Curl example: curl -H "Api-Key: XXX" --data "query=some_username" https://api.tgdev.io/tgscan/v1/search

Successful result looks like:

{
  "status": "ok",
  "result": {
    "user": {
      "id": <int>,
      "username": <str|null>,
      "first_name": <str>,
      "last_name": <str|null>
    },
    "username_history": [
      {
         "username": <str>,
         "date": <str>
       },
    ],
    "id_history": [
      {
         "id": <str>,
         "date": <str>
       },

    ]
    "meta": {
      "search_query": <str>,
      "known_num_groups": <int>,
      "num_groups": <int>,
      "op_cost": <int>
    },
    "groups": [
      {
        "id": <int>,
        "username": <str|null>,
        "title": <str>,
        "date_updated": <str>
      }
    ]
  }
}      

Account Balance Method

URL: https://api.tgdev.io/tgscan/v1/balance

This method does not accept any arguments.

Curl example: curl -XPOST -H "Api-Key: XXX" --data https://api.tgdev.io/tgscan/v1/balance

Successful result looks like:

{
  "status": "ok",
  "result": {
    "num_credits": <int>
  }
}

Similar Groups Method

This method returns groups similar to the given group. Similarity is calculated as number of same users in groups.

URL: https://api.tgdev.io/tgscan/v1/chat/similar

Required arguments:

  • query - must be a username (without "@"). May be multiple usernames, delimited with comma. Maximum 10 usernames.

Curl example: curl -H "Api-Key: XXX" --data "query=some_username1,some_username2" https://api.tgdev.io/tgscan/v1/chat/similar

Successful result looks like:

{
  "status": "ok",
  "result": {           
    "meta": {                  
      "search_query": [                                                                                                                                        
        <str>,
        ...                                                                                                                                              
      ],                                                                                                                                                       
      "op_cost": <int>                                                                                                                                             
    },                                                                                                                                                         
    "groups": [                                                                                                                                                
      {                                                                                                                                                        
        "username": <str>,                                                                                                                                
        "title": <str>,                                                                                                                               
        "num_users": <int>                                                                                                                                       
      },
      ...
    ]             
  }      
}

Basic User Check

URL: https://api.tgdev.io/tgscan/v1/user/check

Required arguments:

  • query - must be a username (without "@") or Telegram numeric ID

Curl example: curl -H "Api-Key: XXX" --data "query=some_username1" https://api.tgdev.io/tgscan/v1/user/check

Field ".result.meta.known_num_groups" contains a number of groups known for this user. Boolean values in user object mean if there is data in database for that field or not.

Successful result looks like:

{
  "status": "ok",
  "result": {
    "user": {
      "username": <bool>,
      "first_name": <bool>,
      "last_name": <bool>
    },
    "meta": {
      "search_query": <str>,
      "known_num_groups": <int>,
      "op_cost": 0
    }
  }

Though this method is free (it costs zero credits) you must have non-zero credits balance to access this method.

Test Methods

  • URL: https://api.tgdev.io/tgscan/v1/test/search
  • URL: https://api.tgdev.io/tgscan/v1/test/chat/similar
  • URL: https://api.tgdev.io/tgscan/v1/test/user/check

Arguments are same as for live API methods.

You can use only test API keys with test methods. Results of test methods contain random data, the structure of test result is same as in result of live search method.

Though credits are not withdrawn from your account's balance when you use test methods, you still need to have real credits on your balance to be able to use test methods.