UrlTrends API Documentation

Last Revised: Thursday, September 15, 2005 13:16 PST

GetInfo Call Information:

The GetInfo call will allow you to see all of the current information for any Url that we have on file. It is also the only way to add a url to our database to be monitored.

GetInfo is the most complex, yet versatile call that you can make to the UrlTrends API. Depending on the options set you can retrieve the current rankings for a Url, Add a Url and retrieve the results, and Add a url and not retreive the results (specifics on why you would or wouldn't like to do this are outlined below).

GetInfo Options:

GetInfo accepts the following options when making a request.

Name Information (acceptable values) Required

command GetInfo Yes

url The only valid value would be a Url Encoded string containing the url that you are requesting information on. Yes

update Set value to 1 to add the url to our systems if it is not already present. Set it to 0 if you do not want to add the url to our systems. If it is not set it will default to 0.

Note: This option is ignored if your API plan does not allow you to add urls to our monitoring systems. Currently, this only effects users on the API Basic Plan. No

wait Set value to 1 if you want to wait for the results when we do not have the url in our database. Set it to 0 if you don't want to wait. This option is only used when a url is not in our database and update is set to 1. The default option if the variable is not set is 1.

This setting is the most useful when you have a large list of urls to add to our database. By setting it to 0 you can quickly cycle through all of the urls without waiting for our systems to return the information.

If set to 0 our API adds the url to a queue to be processed later and instantly returns a message to your application so that it is not waiting. Typically within a minute the information will be available for you to access.

If set to 1 your application will wait for us to return the information. If we have the url in our database our API will typically respond within 0.1 second with the information requested. If the url is NOT in our database your application will be waiting from 2 to 60 seconds while we gather the information. If you set this variable to 1 make sure that your application will wait up to 60 seconds before timing out. No

sendifavail If set to 1 we will reply to your request with the search engine information for a url. If set to 0, we will only reply with the date that the urls information was last updated. It defaults to 0 if not set.

This is most useful to see if a urls information has been updated. It should be set to 0 if the only purpose of the query is to see if the information has been updated. The extra information not sent will save both you and UrlTrends on unnecessary bandwidth usage. No

apikey Your 64 character API key assigned to you. Yes

Note: All commands and their values are case sensitive. The only exception is the value for url.

You can make either HTTP GET or HTTP POST calls to our API server to access the information. Our API responds back with a simple XML response.

GetInfo Example:

An example GET request would look like the following:

http://api.urltrends.com/api.php?command=GetInfo&url=http%3A%2F%2Fwww.domainname.com&update=1&wait=1&sendifavail=1&apikey=API_KEY_HERE

This example API call would return something similiar to the following:

<?xml version="1.0" encoding="utf-8"?>
<Result>
	<UrlInfo>
		<URL>http://www.urltrends.com</URL>
		<URLID>7</URLID>
		<Title>UrlTrends :: Website Analytics & Trends, Online Competitive Intelligence Research and Search Engine Position Tracking Tools</Title>
		<Description>Monitoring 62,666 Url's Search Engine Ranking Trends Tracking 417,770 Keywords on 10,271,799 URLs Username: Password: Click Here to Register Forget your September 13th, 2005 - Trend Reports now display the date a website was first......</Description>
		<OnlineSince>Unknown</OnlineSince>
		<FirstMon>2004-12-28</FirstMon>
		<Adult>No</Adult>
		<Updated>2005-09-15</Updated>
		<Rankings>
			<Rank_PR>4</Rank_PR>
			<Rank_Alexa>16701</Rank_Alexa>
			<Link_Out>26</Link_Out>
			<Link_Google>237</Link_Google>
			<Link_Yahoo>5200</Link_Yahoo>
			<Link_MSN>4884</Link_MSN>
			<Link_Alexa>0</Link_Alexa>
			<Link_AllTheWeb>2660</Link_AllTheWeb>
			<Link_AltaVista>4400</Link_AltaVista>
			<Link_Teoma>52</Link_Teoma>
			<Blog_IceRocket>38</Blog_IceRocket>
			<BM_Delicious>227</BM_Delicious>
			<BM_Furl>25</BM_Furl>
		</Rankings>
		<DMOZ>
			<Cat path="Computers/Internet/Searching/Directories/Open_Directory_Project/Sites_Using_ODP_Data">Top/.../Open Directory Project/Sites Using ODP Data</Cat>
		</DMOZ>
		<Cache>
			<Cache_Archive url="http://web.archive.org/web/*/http://www.urltrends.com">0</Cache_Archive>
			<Cache_Google url="http://www.google.com/search?q=cache:http://www.urltrends.com">1</Cache_Google>
			<Cache_UrlTrends url="http://www.urltrends.com/cache.php?id=7&view=all">11</Cache_UrlTrends>
		</Cache>
	</UrlInfo>
	<API>
		<ResponseCode>200</ResponseCode>
		<RemainingQueries>9994101</RemainingQueries>
		<ExecTime>0.020</ExecTime>
	</API>
	<PassThru></PassThru>
</Result>

Name	Information (acceptable values)	Required
command	GetInfo	Yes
url	The only valid value would be a Url Encoded string containing the url that you are requesting information on.	Yes
update	Set value to 1 to add the url to our systems if it is not already present. Set it to 0 if you do not want to add the url to our systems. If it is not set it will default to 0. Note: This option is ignored if your API plan does not allow you to add urls to our monitoring systems. Currently, this only effects users on the API Basic Plan.	No
wait	Set value to 1 if you want to wait for the results when we do not have the url in our database. Set it to 0 if you don't want to wait. This option is only used when a url is not in our database and update is set to 1. The default option if the variable is not set is 1. This setting is the most useful when you have a large list of urls to add to our database. By setting it to 0 you can quickly cycle through all of the urls without waiting for our systems to return the information. If set to 0 our API adds the url to a queue to be processed later and instantly returns a message to your application so that it is not waiting. Typically within a minute the information will be available for you to access. If set to 1 your application will wait for us to return the information. If we have the url in our database our API will typically respond within 0.1 second with the information requested. If the url is NOT in our database your application will be waiting from 2 to 60 seconds while we gather the information. If you set this variable to 1 make sure that your application will wait up to 60 seconds before timing out.	No
sendifavail	If set to 1 we will reply to your request with the search engine information for a url. If set to 0, we will only reply with the date that the urls information was last updated. It defaults to 0 if not set. This is most useful to see if a urls information has been updated. It should be set to 0 if the only purpose of the query is to see if the information has been updated. The extra information not sent will save both you and UrlTrends on unnecessary bandwidth usage.	No
apikey	Your 64 character API key assigned to you.	Yes