Knowledge Base

Question

Making your first API Request

Answer 1

Hello there! This getting started tutorial is meant for technical folks who aren't too familiar with APIs, and want a zero-to-hero guide to grabbing data out of the Appfigures API. If you're interested in more advanced topics just skip on down to the Next steps section below.

Starting out

Congrats on getting started with the Appfigures API!

We'll get our feet wet by making some really simple API requests and then we'll talk about the next steps you can take to get all the information you need out of the API in a format that works for you.

When getting started with anything in life, there's really nothing more heart-warming than a list of sequential steps to follow, so let's start this off on the right foot:

Register an API Client

Before we can really do anything with the API we need to create what's called a client. We use our client's key to identify ourselves every time we make an API request. This is done so that the API knows exactly who is making the request, especially if we ever need to make requests on behalf of someone else (which we won't do in this tutorial).

Head on over to https://appfigures.com/developers/keys
If you haven't already made an API client, go ahead and click the button to create a new one. If you already have one just click it and skip to Create the Request
Give your new client a name. Make it something meaningful; if you plan on creating a full-blown app, this is the name your users will see when they log in. Next you'll need to choose permissions, or features your client will need access to. If you're not sure which permissions to choose just select "Read" for all of them. Remember, you can always delete clients and make new ones as needed.
You'll now be presented with two different keys: a client key and a secret key. You use them for OAuth 2.0, but for this tutorial we will by using Personal Access Tokens so you won't need them. You will, however, need to open the settings of the API client you just made and select 'Create Personal Access Token'. Keep that token safe like you would a password, since it allows access to your account.

Create the request

There are several ways to make API requests but let's use the simplest one: your trusty web browser. While it limits the type of requests we can make (after all browsers weren't built for this kind of thing), it's perfect for our humble needs at the moment. All we need to do is plop a url with the following format into our browser and it'll present us with the result from the API in the same way it usually presents us with web pages:

https://api.appfigures.com/v{version}/{some/route}?access_token={personal_access_token}

Before we can actually use this link we'll need to replace {version} with the version of the API we want to use, {some/route} with the specific resource we need (e.g reviews, sales, ranks), and the last one, well, you get the idea. Note that this isn't the most secure way to pass the access token to us -- you can learn more about the preferred way in our full documentation -- but this is the easiest way to get started.

Okay, enough theory. Let's start by asking the API for a list of all the countries it supports. Copy the link below into your browser, replace {personal_access_token} with your personal access token (should be in your clipboard from step 4 above) and hit enter:

https://api.appfigures.com/v2/data/countries?access_token={personal_access_token}

Rejoice!

You should now be presented with the list of every country supported by the API in the raw JSON format. It should look something like this:

{
  "AD": {
    "iso": "AD",
    "name": "Andorra",
    "apple_store_no": ""
  },
  "AE": {
    "iso": "AE",
    "name": "UAE",
    "apple_store_no": "143481"
  },
  "AF": {
    "iso": "AF",
    "name": "Afghanistan",
    "apple_store_no": ""
  },
  . . .
}

Time to play

You'll notice that we chose the data/countries route for the previous request, which is one of the many available routes (though arguably one of the less exciting ones). Each route represents a type of data that the API deals with. Let's try some more interesting ones:

The reviews route

Fetch the first 100 reviews of all the apps in your account:

https://api.appfigures.com/v2/reviews?count=100&access_token={personal_access_token}

The sales route

Fetch your all time sales stats for all your apps:

https://api.appfigures.com/v2/sales?access_token={personal_access_token}

Some cool things to try

Translate your reviews - If we teak the reviews example above to include the parameter lang=es, all the reviews will be translated to Spanish:
```
  https://api.appfigures.com/v2/reviews?count=100&lang=es&access_token={personal_access_token}
```
You can read about all the reviews route's options right here.
Export as CSV - The default output format of the API is JSON but some routes can also output CSV (which Excel can import). These routes include Sales, Ads, and Ranks. See the API reference for detailed information on how to use these, but the gist is that you need to add the format parameter to your request with the value csv. For example:
```
  https://api.appfigures.com/v2/sales?format=csv&access_token={personal_access_token}
```
Access public data - By default the API will only let you access public data about your own apps. If you're interested in market research and tracking other apps should check out Partner API Access.

Next steps

Using a programing language you'll be able to make any type of request (not just GET) and customize your output format to suite your specific needs. To get started check out some of the sample code we have available.

Using OAuth 2.0

In this tutorial we focused on using Personal Access Tokens to authenticate with the API, which is great when we need to get data out of our own Appfigures account. If you'd like build an API client which other Appfigures members can use by logging in with their credentials you'll need to use OAuth. You can read more about authenticating and OAuth 2.0 over at the documentation area.