The Weblogs.com ping service is used to automatically inform Moreover whenever you update content on your site. The service receives notification (a "ping") from your site that you have added new content, and if all goes well, Weblogs.com adds your site to a list of recently changed weblogs.

If you're not using blogging software that automatically pings Weblogs.com, or if you're looking for more information on how to ping, this page will help you get your ping client up and running:

1. Setting Up Your Ping Service Interface
   1. A Quick Word on Domains
   2. Setting up an XML-RPC Client
      1. Example XML-RPC Request
      2. Example Extended Ping XML-RPC Request
      3. Example XML-RPC Response
   3. Setting up a REST Client
      1. Example HTTP GET request
2. Processing Model, Error Responses, and Rejected Pings
3. Published Weblog Lists: changes.xml and shortChanges.xml
   1. The <weblogUpdates> Element
   2. The <weblog> Element

Setting up Your Ping Service Interface

Weblogs.com has two interfaces available: REST and XML-RPC. Both follow standard industry practices for ping server interfaces. You simply configure your blogging software to ping Weblogs.com anytime you publish new content.

A Quick Word on Domains

Weblogs.com manages two domains for normal and extended ping services: www.weblogs.com and rpc.weblogs.com. While both domains currently offer the same ping services, your ping clients and changes XML consumers should only refer to the rpc.weblogs.com domain as www.weblogs.com may not support pinging in the future.

[↑ Top]

Setting up an XML-RPC Client

The XML RPC request should be constructed based on:

RPC endpoint:  http://rpc.weblogs.com/RPC2

Method name:  weblogUpdates.ping OR weblogUpdates.extendedPing

Parameters: (should be sent in the same order as listed below)


4. name of site (string, limited to 1024 characters)
5. URL of site or RSS feed (string, limited to 255 characters)


Optional Parameters:
6. the url of the page to be checked for changes (string, limited to 255 characters) (non-optional when using the extended ping interface)
7. the URL of an RSS, RDF, or Atom feed (when using the extended ping interface) (string, limited to 255 characters, non-optional when using the extended ping interface)
8. a name (or "tag") categorizing your site content (string, limited to 1024 characters. You may delimit multiple values by using the '|' character.)


The XML RPC response will have a Struct with three members:


9. flerror (Boolean) which is true/1 if an error occurred
10. message (string) which contains "Thanks for the ping."(if successful) or an error message.
11. legal (string) which contains "You agree that use of the Weblogs.com ping service is governed by the Terms of Use found at www.weblogs.com."
    
    If the call succeeds, the weblog will appear in shortChanges.xml on the next generation, usually within 5 to 10 minutes.
    ↑ [Top]

    Example XML-RPC Request:

    POST /RPC2 HTTP/1.0
    User-Agent: Java
    Host: rpc.weblogs.com
    Content-Type: text/xml
    Content-length: 250
    
    <?xml version="1.0"?>
    <methodCall>
    <methodName>weblogUpdates.ping</methodName>
    <params>
    <param>
    <value>Someblog</value>
    </param>
    <param>
    <value>http://spaces.msn.com/someblog</value>
    </param>
    </params>
    </methodCall>
    
    
    ↑ [Top]

    Example Extended Ping XML-RPC Request with multiple category tags:

    POST /RPC2 HTTP/1.0
    User-Agent: Java
    Host: rpc.weblogs.com
    Content-Type: text/xml
    Content-length: 300
    
    <?xml version="1.0"?>
    <methodCall>
    <methodName>weblogUpdates.extendedPing</methodName>
    <params>
    <param>
    <value>Someblog</value>
    </param>
    <param>
    <value>http://spaces.msn.com/someblog</value>
    </param>
    <param>
    <value>http://spaces.msn.com/someblog/PersonalSpace.aspx?something</value>
    </param>
    <param>
    <value>http://spaces.msn.com/someblog/feed.rss</value>
    </param>
    <param>
    <value>personal|friends</value>
    </param>
    </params>
    </methodCall>
    
    
    ↑ [Top]

    Example XML-RPC Response:

    HTTP/1.1 200 OK
    Connection: close
    Content-Length: 333
    Content-Type: text/xml
    Date: Sun, 30 Sep 2001 20:02:30 GMT
    Server: Apache
    <?xml version="1.0"?>
     <methodResponse>
    
      <params>
       <param>
        <value>
         <struct>
          <member>
           <name>flerror</name>
           <value>
            <boolean>0</boolean>
           </value>
          </member>
          <member>
           <name>message</name>
           <value>Thanks for the ping.</value>
          </member>
          <member>
           <name>legal</name>
           <value>You agree that use of the Weblogs.com ping service is governed by the Terms of Use found at www.weblogs.com.</value>
          </member>
         </struct>
        </value>
       </param>
      </params>
    </methodResponse>
    

    
    ↑ [Top]

    Setting up a REST Client

    Weblogs.com accepts form-based HTTP POST and GET requests for non-extended pings. For example, the following is a valid HTTP GET ping request:

    URL:  http://rpc.weblogs.com/pingSiteForm
    
    Parameters:

12. name= <Name of Blog> (limited to 1024 characters)
13. url= <URL of Blog> (limited to 255 characters)
    
    Optional Parameter:
14. changesURL= <URL of xml, rdf, or atom feed> (limited to 255 characters)
    ↑ [Top]

    Example HTTP GET request:

    http://rpc.weblogs.com/pingSiteForm?name=InfraBlog&url=http%3A%2F%2Finfrablog.verisignlabs.com
    ↑ [Top]

    Processing Model, Error Responses, and Rejected Pings

    Both the REST and XML-RPC interfaces are synchronous and will attempt to ensure that your client submitted a valid ping. Examples of invalid pings include, but are not limited to:

    • Your ping is missing a required parameter;
    • Your ping contains a parameter that exceeded its length limitation;
    • Your ping contains a URL parameter that does not start with "http://";
    • Your ping contains a URL parameter that refers to a known invalid host;
    • Your XML-RPC request contains an ENTITY reference.

    The core Weblogs.com ping processing service is based upon an asynchronous model. This means that even though your client receives an initial "Thanks for the ping" synchronous response, your ping may be dropped or filtered later for various reasons (not limited to the following):

    • Your ping client may be pinging too fast (more than one ping per 30 minute interval);
    • Your ping may refer to a blog host that has requested to be removed from this service.
    ↑ [Top]

    Published Weblog Lists: changes.xml and shortChanges.xml

    Every five minutes, Weblogs.com publishes two documents:

    1. changes.xml contains the latest 60 minutes of pinged weblogs. Applications should not read this file more often than once per hour.
    2. shortChanges.xml contains the top 5 minutes of changes.xml. The top 100 of these sites are shown at Weblogs.com.

    In addition, once per hour Weblogs.com publishes the previous hours worth of pinged weblogs as XML and HTML documents. For example, you can find the list of Weblogs that were pinged during the 05 GMT hour of 18 October 2005 under www.weblogs.com/2005/10/18/05.xml.

    Weblogs.com supports HTTP request and response headers like "If-Modified-Since" and ETag to help you save bandwidth by only downloading the changes files that you haven't already seen.

    Both changes.xml and shortChanges.xml conform to the following XML document structure:

    <weblogUpdates version="2" updated="Mon, 10 Oct 2005 14:10:00 GMT" count="1384779">
        <weblog name="Weblogs.com" url="http://www.weblogs.com" when="1"/>
    
        <weblog name="My Blog site" url="http://www.myblogsite.com" when="2"/>
        <weblog name="Another site" url="http://www.anothersite.com" when="3"/>
    </weblogUpdates>

    The www.weblogs.com/rssUpdates service produces changes.xml and shortChanges.xml that conform to the following XML document structure:

    <weblogUpdates version="2" updated="Mon, 10 Oct 2005 14:10:00 GMT" count="1384779">
    
        <weblog name="Weblogs.com" url="http://www.weblogs.com" 
                   rssUrl="http://www.weblogs.com/rss.xml" when="1"/>
        <weblog name="My Blog site" url="http://www.myblogsite.com"  
                   rssUrl="http://www.myblogsite.com/rdf.xml" when="2"/>
        <weblog name="Another site" url="http://www.anothersite.com"  
                   rssUrl="http://www.anothersite.com/atom.xml" when="3"/>
    </weblogUpdates>

    ↑ [Top]

    The <weblogUpdates> Element

    changes.xml and shortChanges.xml contain a single weblogUpdates element. It has three attributes: version, updated and count; and any number of weblog sub-elements.

    1. version is a number; we're currently on version number 2. However if the format changes substantially, we have an easy way to support this version in addition to the new one.
    2. updated is a string, a date-time in HTTP 1.0 format, it indicates when changes.xml was last updated.
    3. count is a number, it indicates how many times changes.xml has been updated since its deployment.
    4. Note that weblogUpdates is sorted in reverse-chronologic order.
    ↑ [Top]

    The <weblog> Element

    weblog has three attributes: name, url and when:

    1. name is a string, the name of a weblog.
    2. url is a string, its URL.
    3. rssUrl is a string, the URL of an RSS, RDF, or Atom feed for the weblog.
    4. when is a number of seconds. If you subtract this number from the updated attribute of weblogUpdates, you'll get the time that Weblogs.com was pinged with that weblog.