API Guide

From GeoMonkey Wiki
Jump to: navigation, search

In order to use the GeoMonkey API, you will need to complete the following steps:

Contents

Register for a user account

Navigate your web browser to the MapWith.Us website and sign up for a user account. To do this, you will need to choose a unique username and password, provide a registration email address, and enter some captcha text to prove that you are human. Note that if you already have an account and know your API key and secret, you can skip these first few steps.

Create an application

Once your MapWith.Us account has been created, you will need to navigate to your user profile. Once at your profile, use the links on the right of the page to navigate to Settings -> Applications. Once there, select the New link from the applications section on the page (see screenshot below).

API account screenshot1.png

On the following page, fill in the relevant fields for your application. Most likely, it will look something like this:

API account screenshot2.png

At this point, you can go ahead and save your application.

Copy your API key and secret

Now, you should see your application listed in your profile applications listing. If you see it, click on the name of your application to see your the details of your API key and secret, you will need these to access the API, so writing them down would probably be a good idea.

API account screenshot3.png

Access the API

Step 1: Acquire a Streetbrew token

Hit the Login endpoint with valid credentials

  • Valid credentials are a username/password; Facebook UID and session key; Twitter UID, token and secret; or OpenID URL and token.
  • To hit the login servlet with your username and password, set the HTTP Basic Authorization header with your Base64 encoded username and password separated by a colon (E.G. base64Ec("username:password").
  • Optionally supply a previously used token as a parameter accessor to indicate that you wish to continue using it if possible.

If the previously used token is still valid, it is returned in the response's token field. If a new token has been created for you, it is returned in the response's newtoken field.

For example:

GET /brew/api/streetbrew/login?app_key=your_api_key&accessor=your_token HTTP/1.1
Host: www.streetbrew.com
Accept: */*
Authorization: Basic {user:pass|base64}

HTTP/1.1 200 OK
Content-Type: text/xml;charset=utf-8

<?xml version="1.0" encoding="UTF-8"?>
<success>
  <request>http://www.streetbrew.com/brew/api/streetbrew/login</request>
  <message>Renewed access token.</message>
  <avatar_url>/r/FileView/file/f/F123/t/true/k/abcdef/012.jpg</avatar_url>
  <username>your_username</username>
  <joined>July 15, 2009</joined>
  <wall_acc>100.0</wall_acc>
  <token>your_token</token>
  <facebook_linked>false</facebook_linked>
  <post_acc>200.0</post_acc>
  <userid>123</userid>
  <twitter_linked>false</twitter_linked>
  <last_login>December 9, 2010</last_login>
</success>

Step 2: Query other endpoints using your Streetbrew token

When querying API endpoints, use the following HTTP header:

  • Authorization: Streetbrew

Additionally, supply the given Streetbrew token as the parameter accessor in your request.

For example:

GET /brew/api/streetbrew/events?app_key=your_api_key&accessor=your_token&wallid=10 HTTP/1.1
Host: www.streetbrew.com
Accept: */*
Authorization: Streetbrew

HTTP/1.1 200 OK
Content-Type: text/xml;charset=utf-8

<?xml version="1.0" encoding="UTF-8"?>
<events>
  <event>
    <eventid>2666</eventid>
    <title>Test Event Too</title>
    <text><![CDATA[Just a little test, that's all.]]></text>
    <posterid>21</posterid>
    <poster_username>opt1mal</poster_username>
    <avatar_url>/r/FileView/file/f/F1184/t/true/k/kTkCxknS/1276122271932.jpg</avatar_url>
    <start_date>1276557211000</start_date>
    <end_date>1276557511000</end_date>
    <created>1276557080000</created>
    <attendance_status>1</attendance_status>
  </event>
</events>