API Usage for URL search (2.0)
It's just an HTTP GET, and the page will return some simple text/XML/JSON/serialize indicating the url, adding date and some other information.
- http://{your_api_host}/2.0/url/?url=http://google.com&pkey=&out=1
- http://{your_api_host}/2.0/url/?url=http://eicar.org&pkey=&out=1
- http://{your_api_host}/2.0/url/?url=http://www.eicar.org/download/eicar.com&pkey=&out=1
Parameters
These are the input values that specify your request.
| Parameter | Description |
| pkey | (REQUIRED) Each subscriber to API Web Services is uniquely identified by an ID sequence and every request to Web services requires this ID. |
| url | Search by URL, substring, url-part. Required sheme (http, https, ftp) (like: http://some.bad.com/virus.exe). |
| out | You can select your response format with "out" parameter. The default is 0 — text, 1 — JSON, 2 — XML, 3 — PHP SERIALIZE . By default as 0 |
| qt | Optional parameter for show query process time. By default as 0 |
Search query
- Please configure your request as can be clearly, search is performed by a substring, but result is given only one.
- Always use protocol prefix (sheme) for url search (http://, https://, ftp://)
- If you check the host, the decision to add (www.) prefix or not is up to you.
- For exact search, always compare the query with the result!
- URL and domain can also be "url encoded". In PHP, this can be done using the urlencode() function.
Returns
API returns XML, JSON or text which means it can be used within any programming language and on any platform.Response fields
Please note that the number of response parameters may change from time to time to tell you more about particular threats.
- url — full URL from database.
- md5 — hash of latest downloaded content
- add_time — adding url date and time
- download_time — date and time of latest downloaded content
- valid — validation flag. 1 - url is active, 2 - url is offline, 3 - deleted (special)
- host — domain name
- ipv4 — latest catched IP address of domain
- country — latest catched hosted country
Returns for unknown URL
Means that the processed checks are OK and the tested url, domain or IP address is not located at one of the known malware or suspicion DB.
Error reporting
Any errors reported, within the control of the API, will be presented in the simple text format and started from "ERROR:"
- ERROR: Validating API request format failed, please check your API request.
- ERROR: Authenticating customer failed, please check your authentication ID.
- ERROR: Authenticating customer failed, your authentication ID is disabled.
- ERROR: API determines some internal errors, please try again or contact us.
Server's response with Malware parameter
All URL listed in database is dangerous, but for FP zero tolerance you can use this parameter. Flagged as malware links were loaded our crawlers and clearly confirmed as malicious.
Use &malware=1 parameter for filtering only 100% risk URLs.