API

This API allows other applications to trigger Choosy's functionality. The API will function whenever Choosy is installed, even if it is not set as the default browser. It is URI based, so it is easy to use from bookmarklets and browser plugins.

Requirements

The original beta release (version 0.9.0) did not include this API. To use the API you must download version 0.9.1 or later. If you have an appropriate version of Choosy installed this link should trigger an “all browsers” prompt: Choosy API prompt

Functionality

The Choosy API works using Mac OS X's URI system. A custom URI scheme has been defined, and Choosy can be triggered using this URI scheme. The general form of a Choosy API call is:

x-choosy://api_method/website_url

  • Prompting to select a browser

    API method
    prompt.all or prompt.running
    Example
    x-choosy://prompt.all/http://www.google.com
    x-choosy://prompt.running/http://www.google.com
    Description
    These URLs will open www.google.com in Choosy, bypassing the user's behaviour settings and forcing Choosy to display a browser prompt. Using prompt.all will prompt the user to select from all browsers. Using prompt.running will prompt the user to select from the running browsers. If only one browser is running prompt.running will automatically use that browser. If no browsers are running prompt.running will behave like prompt.all.

  • Using the user's favourite browser

    API method
    best.all or best.running
    Example
    x-choosy://best.all/http://www.google.com
    x-choosy://best.running/http://www.google.com
    Description
    These URL will open www.google.com in Choosy, bypassing the user's behaviour settings and forcing Choosy to use the user's favourite browser. Using best.all will use the favourite browser, even it it's not running. Using best.running will use the best running browser. If no browsers are running best.running will behave like best.all.

Code Examples

AppleScript

To use any API method use the following code:

set api_method to "prompt.all"
set the_url to "http://www.google.com"
open location "x-choosy://" & api_method & "/" & the_url

For Choosy's default behaviour (i.e. the open API method) you can also use this:

set the_url to "http://www.google.com"
tell application "Choosy" to open location the_url

From the Terminal

export api_method="prompt.all"
export the_url="http://www.google.com"
open "x-choosy://${api_method}/${the_url}"

Javascript in a browser

var api_method = "prompt.all";
var the_url = "http://www.google.com";
window.location = "x-choosy://" + api_method + "/" + the_url;

Objective-C

NSString *api_method = @"prompt.all";
NSString *the_url = @"http://www.google.com";
[[NSWorkspace sharedWorkspace] openURL:[NSURL URLWithString:
	[NSString stringWithFormat:
		@"x-choosy://%@/%@",
		api_method,
		the_url]]];

Other languages

If your favourite language is missing from the list and you want to donate some example code or you think I should provide some, let me know.

Feedback

As with everything else in Choosy, your feedback on the API is greatly appreciated. Use the Choosy feedback page or email george@choosyosx.com and let me know what you think!

Top of page ↑