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.
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.
Non-successful API results look like:
{
"status": "error",
"result": {
"message": <str>
}
}
The field ".result.message" contains short error description.
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.
URL: https://api.tgdev.io/tgscan/v1/search
Required arguments:
query - must be a username (without "@") or Telegram numeric IDCurl 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>
}
]
}
}
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>
}
}
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>
},
...
]
}
}
URL: https://api.tgdev.io/tgscan/v1/user/check
Required arguments:
query - must be a username (without "@") or Telegram numeric IDCurl 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.
https://api.tgdev.io/tgscan/v1/test/search
https://api.tgdev.io/tgscan/v1/test/chat/similar
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.