Using the API

You can access the URL schemes in the index using our XML API. 
Due to the increasing demand on our API we are changing the terms concerning it's use in two ways; first, you need to identify your app with your API key and second, the amount of calls is limited. The limit may depend on the used endpoint.

API key

Since version 1.2 it is mandatory to supply your API key when making an API call!
You can request an API key on your account page, right after you log in.
(Older versions of the API will be discontinued on march 1st, 2012)

Usage limits

When you use the handleOpenURL API please keep in mind that there's a limit to the amount of calls you are allowed to make. We have set this amount to 150 calls per day. This may change in the future.
We have set this limit so we can keep the API available to all. Please keep track of the amount of calls you make and keep consecutive calls far enough apart to not run into the limit.
If you do run into the limit, you will be warned, you will receive a "503 Service Temporarily Unavailable" header response. (The document will have no content)
Next to the 503 there will be a Retry-After header with the GMT date after which you will have access again.
Please note: You must respect this directive. If you do not respect this directive, there will be penalty time added to the service block.
To make sure you do not run into the usage limits you should cache the results.

Commercial use

We at handleOpenURL.com work hard to provide a well organised, well kept, freely available index for developers as a reference and test platform. If you would like to use the entries from the handleOpenURL.com index within your paid app you have to pay a yearly license fee. Please contact us for more information.


Using the handleOpenURL API is simple, there are 2 endpoints:

Search

You can search for a specific keyword within the URL schemes using the search endpoint. The search query is performed within the scheme itself and within any tags related to the scheme.

For example, if you want to find apps which are related to Facebook, you can call:

http://handleopenurl.com/api/v1.2/search.xml?apikey=YOUR_API_KEY&key=facebook

You will receive the following response:

<?xml version="1.0"?>
<handleopenurl>
<CFBundle>
<URLScheme>duoxx</URLScheme>
<DisplayName>Duo</DisplayName>
</CFBundle>
<CFBundle>
<URLScheme>connections</URLScheme>
<DisplayName>Connections</DisplayName>
</CFBundle>
<CFBundle>
<URLScheme>fb</URLScheme>
<DisplayName>Facebook</DisplayName>
</CFBundle>
</handleopenurl>

The usage limit for the search endpoint is 150 calls per day.

List

You can list all entries in the index using the list endpoint. The list endpoint lists 50 entries per page.

For example if you want to get the fourth page of the listing you call:

http://handleopenurl.com/api/v1.2/list.xml?apikey=YOUR_API_KEY&page=4

You will receive the following response:

<?xml version="1.0" encoding="UTF-8"?>
<handleopenurl>
<CFBundle>
<URLScheme>notitas</URLScheme>
<DisplayName>Notitas</DisplayName>
</CFBundle>
<CFBundle>
<URLScheme>music</URLScheme>
<URLScheme>audio-player-event</URLScheme>
<DisplayName>original+iPod+%2F+Music+app</DisplayName>
</CFBundle>
...
...
<CFBundle>
<URLScheme>immolocatif</URLScheme>
<DisplayName>Rentabilit%C3%A9+Immo+locatif</DisplayName>
</CFBundle>
<page>4</page>
<pagecount>6</pagecount>
</handleopenurl>

The usage limit for the list endpoint is 150 calls per day.