Documentation

  1. What are Sitemaps?
    1. Supporting Search Engines
  2. Getting Started
  3. API
    1. Overview
    2. Making an API Call
    3. Response Data
    4. Ping Queue and Reports

What are Sitemaps?

Sitemaps are a standard way of listing all the pages in your website in an XML format that can be read by search engines to help them index your website. A digital table of contents if you will.

All the search engines that support Sitemaps allow you to "ping" them with the URL to your sitemap when you've updated it. This will mean that they are aware that your Sitemap should be checked for updates, and hopefully will result in your site ranking better in search results. The "ping" part is where we come in. We save you having to manually submit your Sitemap to every search engine when you've updated it. Instead you just call our API with the Sitemap URL you want to ping the search engines with and we do the rest!

For more information on the Sitemaps format head over to the offical Sitemaps website. It has great documentation!

Supporting Search Engines

The following search engines currently support sitemaps:

  • Google
  • Yahoo!
  • Ask.com
  • Live Search
  • Moreover.com

Getting Started

We've made it really simple for you to get things rolling with PingMyMap. Just follow the yellow brick road...

  1. Sign Up for an account
  2. Add your site
  3. Verify that you own the site you've added

Great stuff! Now you're ready to call our API and send out our carrier pigeons to the darkest corners of the web.

API

Overview

You must verify a site under 'My Sites' in your account before you can submit any Sitemaps on it to our API.

All API calls should be made via the base URL http://api.pingmymap.com. The API is versioned, so to use version 1 of the API just append /v1/ to the base API URL. At the moment there is only one version of the API, but we may add more versions in future if we ever have to break backwards compatibility (perish the thought!).

Making an API Call

To notify our pigeons that your Sitemap has been updated, simply call our API like this:

http://api.pingmymap.com/v1/?url=http://YOURSITE.COM/sitemap.xml&key=YOUR_API_KEY

Just replace the url parameter with your the URL for your sitemap. The sitemap filename can be anything as long as it ends in .xml, .xml.gz or .gz. You can find your API key at the top of 'My Sites' when you're logged in to your account. You'll also notice in 'My Sites' that you can just view and copy the API URl for each site without having to manually construct it yourself. Nice!

If you have more than one Sitemap on your website then just call our API for each Sitemap, passing through the respective URL for each one.

You can call our API from whatever your scripting language of choice may be. If the language supports HTTP connections or has a library to handle them, then you're set! In most cases you'll probably want to call our API from the script that generates your Sitemap.

Response Data

Whenever you make a call to our API we'll send you back a response to let you know how things went. At the moment we're returning responses in JSON format only. As this is a well supported (lots of native functions and libraries for various languages), lightweight data format.

Here are the keys you'll find in the API JSON response:

  • api_version
    • The version of the API that you've called (integer)
  • status
    • A status message describing the success or failure of your API call (string)
  • error
    • true or false (boolean)

You can parse the JSON response and then for example do something neat like send yourself a notification e-mail with the API call status message.

Ping Queue and Reports

Once you've made your API call our pigeons will spring into action and deliver the message to all of the supporting search engines. Within a couple of minutes you can go to 'My Sites' and view the ping report for the Sitemap that you just submitted to our API (if you're already on the 'My Sites' page, give it a r-r-r-refresh!).

Right, that's the nitty gritty out of the way, now on to some code goodness...

API Code Examples

Here are a couple of examples to get you going...

PHP 5 Example:

<?php

  # API Ping URL
  $pingmymap_api_url = 'http://api.pingmymap.com/v1/?url=http://YOURSITE.COM/sitemap.xml&key=YOUR_API_KEY';

  # Default API call result
  $result = false;

  # Init HTTP stream
  $params  = array('http' => array('method' => 'GET'));
  $ctx     = stream_context_create($params);
  # Make HTTP request to API URL
  if(($fp = fopen($pingmymap_api_url, 'rb', false, $ctx)) !== false){

    # Get response
    $response = stream_get_contents($fp);
    # Get headers
    $meta_data = stream_get_meta_data($fp);
    $headers   = $meta_data['wrapper_data'];

    # Check response for any errors
    if($response !== false && stristr($headers[0], '200 OK')){

      # Set API call result status
      $result = true;

      # Display success message
      echo 'Successfully called PingMyMap API!';

      # Parse JSON response
      $parsed_response = json_decode($response);

      # Output JSON response
      var_dump($parsed_response);

    }

  }

  # Display error message
  if(!$result){
    throw new Exception('Error calling PingMyMap API with '.$pingmymap_api_url);
  }

Ruby Example:

require 'rubygems'
  require 'json'
  require 'yaml'
  require 'net/http'

  # API Ping URL
  PINGMYMAP_API_URL = 'http://api.pingmymap.com/v1/?url=http://YOURSITE.COM/sitemap.xml&key=YOUR_API_KEY';

  # Make HTTP request to API URL
  response = Net::HTTP.get_response(URI.parse(PINGMYMAP_API_URL))

  # Check response for any errors
  if response.body and response.code == '200'

    # Display success message
    puts 'Successfully called PingMyMap API!'

    # Parse JSON response
    parsed_response = JSON.parse(response.body)

    # Output JSON response
    y parsed_response

  else
    puts "Error calling PingMyMap API with #{PINGMYMAP_API_URL}"
  end