API Reference

Search

Freebase offers very powerful query services that take advantage of the connectedness of its data, but sometimes it's useful to be able to do simpler full-text queries, for example to look for topics that contain a particular string in them, no matter what property contained it.

This is where the search service comes handy.

Here, for example, we want to search for anything that Freebase knows about Madonna, we can invoke the search service like this

http://api.freebase.com/api/service/search?query=madonna

which will return us a JSON object like this:

   {
       "status": "200 OK",
       "code": "/api/status/ok",
       "result": [
           {
               "alias": [
                   "Madonna Ciccone Ritchie",
                   "Madonna Louise Ciccone Ritchie",
                   "Madonna Louise Ciccone",
                   "Madonna Louise Veronica Ciccone"
               ],
               "article":{"id":"/guid/9202a8c04000641f800000000010ef6a"},
               "guid":"#9202a8c04000641f8000000003ac7f48",
               "id":"/en/madonna",
               "image":{"id":"/guid/9202a8c04000641f800000000b9c4814"},
               "name":"Madonna",
               "relevance:score":98.43017578125,
               "type":[
                   {"id":"/common/topic","name":"Topic"},
                   {"id":"/music/artist","name":"Musical Artist"},
                   {"id":"/people/person","name":"Person"},
                   {"id":"/film/music_contributor","name":"Film music contributor"},
                   {"id":"/music/group_member","name":"Musical Group Member"},
                   {"id":"/book/author","name":"Author"},
                   ....
               ]
           },{
               "alias":[],
               "article":{"id":"/guid/9202a8c04000641f80000000003afd2b"},
               "guid":"#9202a8c04000641f80000000003afd25",
               "id":"/guid/9202a8c04000641f80000000003afd25",
               "image":{"id":"/guid/9202a8c04000641f8000000004566a00"},
               "name":"Madonna","relevance:score":75.266487121582031,
               "type":[
                   {"id":"/common/topic","name":"Topic"},
                   {"id":"/visual_art/artwork","name":"Artwork"}
               ]
           },
           ...
       ]
   }

It's important to note that unlike MQL, free-text search return values based on heuristics and they are ranked by their 'relevance' score, which indicates how relevant the returned Freebase topics were considered to the given text search.

For more information on the search service, its features and how topics are indexed and relevance scores calculated, refer to the search service documentation.

Freebase Suggest

Many search engines provide the feature of help the user type less in the search box by trying to suggest potential search queries based on the text they have already typed.

Not only Freebase sports such a feature on its main web site but also offers a javascript library (written as a jQuery plugin) called Freebase Suggest that you can on your own site and help your user during data-entry tasks by helping them complete their inserts with data coming from Freebase.

So, for example, if your social network site wanted users to list their favorite musicians and books, by using Freebase Suggest not only they would have to type less and validate their choice by seeing a little textual description and an image icon while completing their entry, but you would gain the benefit that all your users would insert the same exact unique identifier instead of their own spelling of the artist, leading to much more precise correlation between user profiles based on their preferences.

Read the Freebase Suggest Documentation for more information.

Geosearch

A currently experimental service that Freebase also offers is another search service that is capable of performing geographical queries over the hundreds of thousands of locations that Freebase knows about.

This search service can be used to obtain information about all the locations of a particular type that are closer than a certain distance to a point, to another location or that belong to a particular region.

Here is a query that lists locations around 'San Diego':

http://api.freebase.com/api/service/geosearch?location=san&20diego&type=/location/location&within=20&order_by=distance&geometry_type=point

For more information on the Geosearch service, read its documentation here.

Developer Tools: