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.

Example:
  • http://{your_api_host}/2.0/url/?url=http://bacc.info&pkey=&out=1
  • http://{your_api_host}/2.0/url/?domain=some.bad.com&pkey=&out=1
  • http://{your_api_host}/2.0/url/?ip=172.16.0.1&pkey=&malware=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).
domain Exact search by domain name (Like: bad.host.com)
ip Exact search by IP address (Like: 192.168.1.1)
malware Optional parameter for filtering "only detected as malware" (100% risk). By default as 0
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.
XML example: <ace2.0> <url>http://myrealtube.net/cd/wmcodec_update.exe</url> <md5>5c24e30a108cbc1d2478305c36946efc</md5> <add_time>1239446589</add_time> <download_time>1239774530</download_time> <valid>1</valid> <host>myrealtube.net</host> <ipv4>1137508554</ipv4> <country>US</country> </aceurl>

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.

COMPLETED: OK. Not found.

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.

http://{your_api_host}/2.0/url/?url=search-string&pkey=&malware=1