Display the Results

The structure of each listing is fairly straight-forward. Each field is a key-value pair, and can be mapped to hash or associative array in most languages. For example, you can grab the business name of the first listing (assuming there is one) like this:

Ruby Example

puts result["results"][0]["name"]

Java Example

    System.out.println(
            root.get("results").get(0).path("name").getTextValue());

PHP Example

echo $result["results"][0]["name"] . "\n";

How you actually display the listings that are returned from the API depends largely your application or website. The following example prints each result in plain text. There are simply too many types of application and web frameworks to include a complete example here.

See also: Listing Schema for information on all listing fields.

Ruby Example

    # print total results found 
    puts "Total results found: #{result["totalResults"]}"
 
    # the results member is an array containing each listings as a nested Hash object
    result["results"].each do |r| 
        puts "#{r["name"]} (#{r["primaryAddress"]["addressLine"]})"  
    end

Java Example

    // print total number of results found
    System.out.println("Total results found: " + 
            root.get("totalResults").getIntValue());
        
    // iterate over the results
    for (org.codehaus.jackson.JsonNode result : root.get("results")) {
        // print the business name and display address
        System.out.println(result.path("name").getTextValue() 
                + " (" + result.path("primaryAddress").path("addressLine").getTextValue() + ")");
    }     

PHP Example

    # print total results found
    echo "Total results found: " . $result["totalResults"] . "\n";

    # the results member is an array containing each listings as a nested associative array
    foreach ($result["results"] as &$listing) {
        echo $listing["name"] . " (" . $listing["primaryAddress"]["addressLine"] . ")\n";
    }

Some other things to consider when displaying the listings:

  • Links to other pages. There can be multiple pages of results, and you should at least provide a method for the user to navigate to the next and previous pages. You could also provide a link to each page, similar to the way yellowpages.com.au does (for example, perform a search for 'cafe' and scroll to the bottom of the page where there are links to pages 1 through 10).

See also: Pagination

  • Display a message if the spell-checker adjusted the query. When the spell checker does this, the originalQuery and totalResults fields will be different.

See also: Spell-Checker

Ruby Example

    # display message if search query was adjusted
    if code == 200
        puts "The search query '#{result["originalQuery"]}' return no results. " + 
             "Returned results for '#{result["executedQuery"]}' instead.";
    end 

Java Example

    // display message if search query was adjusted
    if (code == 200) {
        String original = root.get("originalQuery").getTextValue();
        String executed = root.get("executedQuery").getTextValue();
        System.out.println(
            "The search query '" + original + "' return no results. " + 
            "Returned results for '" + executed + "' instead.");

    } 

PHP Example

    # display message if search query was adjusted
    if ($code == 200) {
       echo "The search query '$results[originalQuery]' return no results. " .
            "Returned results for '$results[executedQuery]' instead.";
    }
  • Reporting on usage. One thing that we require is that you provide us with certain information regarding how your API is used.

See also: Reporting Usage Events for what your obligations are and how to send us events.

That's it! You now know how to call a SAPI endpoint, as well as interpret and display the results.

Next: Learn More.