URLPI Web Service API

Generalizations on the URLPI API

All API usage is tied to an actual account. So you need to create one. When you do, check the box in your profile to get your new key. Otherwise things don't work so well.

The most basic thing you can do is programmatically get a short url back.

These are some basic access methods so that you can add us to your toolbar, add auto-short URLs to your blog (someone want to do Wordpress?) from your long permalinks or any other applications that you dream up for it.

Easy as pi example

Supports both GET and POST methods

http://urlpi.com/api/[method_name]?api_key=[your api key]

such as....

http://urlpi.com/api/www.exampletoshortenme.com

returns

http://urlpi.com/11xx99s

Or similar. Before you send the URL over, encode it! PHP uses something called url_encodes, particularly when it has ampersands which many massive URLs do. The joys of URL programming.

The URLPI API tries to stick to the design ofREST. Methods exposed by the URLPI API require a GET request. Methods that post updates or direct messages require a POST.

Basic Authorization is done via whatever method your library requires. This could be the simple use of a URL such as: http://urlpi.com/api/public_timeline?api_key=APIkeyofyoursFromYourProfile

• Get the public timeline, unauthenticated: curl http://urlpi.com/urls/public_timeline.rss
• Get your friends timeline, authenticated: curl -u APIcode http://urlpi.com/urls/friends_timeline.xml

URLPI Available Methods

Method calls to the URLPI web service require an API Key that you can add in your Profile Settings or email woot @gravit.as. This API is currently under public review. Once you have an approved API Key, you can call the following methods using this syntax:

http://urlpi.com/api/[method_name]?api_key=[your api key]

Some methods will have additional required or optional parameters as specified below. Authentication is done via HTTP authentication. The methods that require authentication, can be done in two different ways authenticate.

General API Methods:

• echo
• authentication_test (requires authentication)

URL Methods:

• get_short_url
• get_stats
• get_daily_urls
• search_urls
• get_urls_similar
• get_urls_people

This gets URLS for a member ID or for a membername.

• get_short_url
• get_urls_entries

---

Note, the above methods are the only ones under active development. We have a standard approach to all of our APIs outlined here, so if you like or would need any of these particular email us to woot @gravit.as with any details on what you need and what mad creation you are going to create.

The next set of things to be implemented is hooking up the URL service to an excellent web stat service we've built, so soon we'll be returning all kinds of interesting stats on a URL for you as well.

As a final note, anyone interested in being able to AUTO create shorturls for other URL shortening services, such as tinyurl and urltea, our ears are open. With a WOOT! or two we'll probably get that done. woot @gravit.as to give us som encouragement.

People Methods:

• search_people
• search_people_by_url
• get_person
• get_persons_urls
• get_persons_progress_on_url
• get_persons_followers
• get_persons_places
• get_persons_tag_cloud
• get_following

Groups Methods:

• get_urls_group
• get_urls_stats_groups

Location Methods:

• get_urls_place

Action Methods

• add_url_by_id (requires authentication)
• add_url_by_name (requires authentication)
• complete_url (requires authentication)

Note remove url removes the url from a profile, it doesn't delete the url

• remove_url (requires authentication)
• update_url (requires authentication)

ATOM Methods:

• introspection
• entry (requires authentication)

---

Common XML Objects

• URL
• Person
• Place

Bells and Whistles

XRDS file for all of the endpoints in the API? If the API endpoints change third party apps could auto-detect the endpoints.