AppURL.org API


These are programmatic interfaces to the AppURL.org directory.

GET /transform/{url}

Returns the native URL associated with the requested http:// or https:// URL.

Request
{url}
A URL to look up and perform transformation on. The URL may begin with http:// or https://. http:// is implied if these prefixes are omitted.
Response
webUrl
The web URL associated with the input url (this is just url itself, possibly with a prepended http://).
nativeUrl
The native URL associated with the input url. This transformation is made after consulting the appropriate appurl.json file.
Example
Request
http://api.appurl.org/transform/yelp.com/search?find_desc=chipotle

Response

{
    "webUrl": "http://yelp.com/search?find_desc=chipotle",
    "nativeUrl": "yelp:///search?terms=chipotle"
}

GET /app/{url}

Returns all information about an app associated with the requested URL.

Request
{url}
A URL corresponding to an app. The URL may begin with http:// or https://. http:// is implied if these prefixes are omitted.
Response
manifest
The full data from the app's appurl.json file.
manifestUrl
The absolute URL to the app's appurl.json file.
timestamp
The Unix time, in milliseconds, when the appurl.json file was added to the AppURL.org database
Example
Request
http://api.appurl.org/app?webPrefix=grid6.us

Response

{
    "manifest": {
        "developer": "AppURL",
        "editions": [
            {
                "downloadUrl": "http://appurl.org/static/pkg/grid6.apk",
                "platform": "android"
            },
            {
                "downloadUrl": "http://appurl.org/static/pkg/grid6.xap",
                "platform": "wp8"
            }
        ],
        "email": "contact@appurl.org",
        "homepage": "http://grid6.us/grid.html",
        "iconUrl": "http://appurl.org/static/grid6logo.png",
        "name": "Grid6",
        "nativePrefix": "grid6.us:/",
        "transforms": [
            {
                "description": "This URL specifies the light grid formations.",
                "native": "{state}",
                "nativeDelim": "/",
                "title": "Grid6 Formation",
                "web": "{state}",
                "webDelim": "/"
            }
        ],
        "webPrefix": "grid6.us/"
    },
    "manifestUrl": "http://grid6.us/appurl.json",
    "rc": 0,
    "timestamp": "2013-03-14T14:32:17"
}

POST /add-app/

Tells Appurl.org to read an appurl.json file at the specified URL. Once read, the appurl.json file will be used to perform web-to-native URL transformations.

Request Arguments
manifestUrl
An absolute URL to an appurl.json file. Must be Content-Type application/x-www-form-urlencoded.
Response
msg
The message will always be "appurl.json file successfully read." on success, and an error message on failure.
Example
Request:
Location
http://api.appurl.org/add-app
POST Data
manifestUrl=http://grid6.us/appurl.json
Header:
Content-Type: application/x-www-form-urlencoded
Response:
{
    "msg": "appurl.json file successfully read.",
    "rc": 0
}

Error Response Codes

All API responses contain a response code key, rc:

  • Successful API calls return an rc of 0
  • Failed API calls return nonzero rc, and a string msg that describes the error

Return code values have the following meanings:

1: App Not Found
No app in our database matches the requested URL.
2: Could Not Match Transformation
An app in our database matches the beginning of the requested URL, but none of the app's transformations match the entire URL.
3: Unable to verify appurl.json File
When providing the URL of an appurl.json file, the response at that URL was a 404 or invalid JSON.
4: Invalid appurl.json File
The provided appurl.json file is malformed. It might contain invalid fields or lack required information. The error message will provide more details.
5: Request Missing Information
We expected fields in this request that we did not receive.
6: Request Contains Invalid Input
This error is rare, and usually means that some input could not be parsed. Possible causes are URLs or JSON files with incorrect syntax.
7: Incorrect Content-Type
The request was sent with an incorrect Content-Type, or was not encoded properly.
8: Does Not Exist
This endpoint does not exist.
9: Unexpected Error
This error should never occur. If it does, please email contact@appurl.org with your request and our response, and we will look into the issue.