Products

The /products resource provides access to product meta data in a variety of ways.

What is a product

Products represent a trackable item in the Appfigures system. Most commonly a product is an app, but since we support more than just apps a product may be an in-app purchase (IAP) or a book.

We collect product data directly from the store the product is sold in. The following properties are available for all products, including products not owned by or shared with your account.

id int The product’s Appfigures-assigned id.
name string Full name of the product.
developer string Name of the developer of the product.
icon string URL to the product’s icon on the store.
vendor_identifier string The ref_no or sku of the product as used by the store to uniquely identify this product.
ref_no int The product’s store id if one is available (only applies to Apple apps currently).
sku string The developer-assigned SKU or package name.
store_id int Id of store this product is sold on.
store string Name of store this product is sold on. Options: “apple”, “google_play”, etc. A full list of stores is available at /data/stores
release_date date Data product was released to the store.
added_date date Date product was added by Appfigures.
updated_date date Date the product was last updated by Appfigures.
version string The product’s current version.
type string Type of product. Options: “app”, “inapp”, “book”.
devices array A list of devices the product is sold on. Options: “Handheld” (Ex. iPhone), “Tablet” (Ex. iPad), “Desktop”.

Products that are owned by or shared with your account will include additional properties specific to your account:

parent_id int If this is an inapp, this is the product id of the parent product.
children array If this is product has inapps, a list of product ids of all the inapps belonging to this product.
features array A list of all additional features the product supports. Options: iads, admob.
source object Information describing the source of the data:

external_account_id
the external account this app came through.

added_timestamp
Date the product was added to your account.

active
Whether the product is actively being tracked by Appfigures.

hidden
Whether the product is visible in the current user’s product list on the site.

type
Whether the app is owned by or shared with your account. Options: own, shared.

Getting a product by its id

GET /products/{id}

id
The Appfigures-assigned id for the product you want to get

Request

GET /products/212135374

Example Response

// GET /products/212135374
{
  "id": 212135374,
  "name": "Rdio",
  "developer": "Rdio",
  "icon": "http://ecx.images-amazon.com/images/I/51IPlKhP19L._SL160_SL150_.png",
  "vendor_identifier": "B004T76OR8",
  "package_name": "B004T76OR8",
  "store_id": 3,
  "store": "amazon_appstore",
  "release_date": "2000-01-01T00:00:00",
  "added_date": "2012-05-30T19:16:43",
  "updated_date": "2013-07-02T21:00:00",
  "version": "2.6.3",
  "source": null,
  "type": "unknown",
  "devices": [
    "Handheld"
  ],
  "price": {
    "currency": "USD",
    "price": "0.00"
  }
}

Searching for products

The Public Data API add-on is required for this route.

Scope

This resource requires the public:read scope.

Request

GET /products/search/{term}?filter={filter}&page={page}&count={count}

Arguments

term REQUIRED
The name of an app or a developer. Prefix with @name= or @developer= if you’d like to search that field only.
filter
Filter to apply to the results: one of ios, mac, google, amazon. Defaults to showing all results
page
Page of results to show. Defaults to the first page
count
Number of results to show in a page. Defaults to 25

Example

// GET /products/search/fob+finder
[
  {
    "id": 6528381,
    "name": "FOB Finder",
    "developer": "Soul Doubt Productions",
    "icon": "http://a715.phobos.apple.com/us/r1000/028/Purple/26/31/e1/mzi.hldsckxh.png",
    "vendor_identifier": "420200383",
    "ref_no": 420200383,
    "sku": "",
    "store_id": 1,
    "store": "apple",
    "release_date": "2011-01-22T00:02:00",
    "added_date": "2011-11-22T23:53:45",
    "updated_date": "2011-11-02T13:00:02",
    "version": "1.76",
    "source": null,
    "type": "app",
    "devices": [
      "Handheld",
      "Tablet"
    ],
    "price": {
      "currency": "USD",
      "price": "0.00"
    }
  }
]
// GET /products/search/@developer=angry
[
  {
    "id": 212138192,
    "name": "GPS Notification",
    "developer": "Angry Face Software",
    "icon": "http://ecx.images-amazon.com/images/I/51amiNe%2BwFL._SL190_CR0,0,190,246_.png",
    "vendor_identifier": "B004QP96SM",
    "ref_no": null,
    "sku": "B004QP96SM",
    "package_name": "B004QP96SM",
    "store_id": 3,
    "store": "amazon_appstore",
    "release_date": "2000-01-01T00:00:00",
    "added_date": "2012-05-30T19:16:49",
    "updated_date": "2013-11-08T02:56:19",
    "version": "1.3",
    "source": null,
    "type": "unknown",
    "devices": [
      "Handheld"
    ],
    "price": {
      "currency": "USD",
      "price": "0.99"
    }
  },
  . . .
]

Getting a product by its id in the store

GET /products/{store}/{id_in_store}

store
The store that the product is from. apple, google_play, amazon_appstore are some valid examples. All available stores can be found by using the /data/stores route.
id_in_store
The product’s unique identifier in the store (Apple ID for iOS/Mac apps, SKU for Google Play, and ASIN for Amazon Appstore apps)

Requests

GET /products/apple/335060889

GET /products/google_play/com.rdio.android.ui

GET /products/amazon/B004T76OR8

Example Responses

// GET /products/apple/335060889
{
  "id": 5985606,
  "name": "Rdio",
  "developer": "Rdio",
  "icon": "http://a1857.phobos.apple.com/us/r1000/081/Purple/v4/f5/6b/0d/f56b0d3b-5a5c-013d-bc08-1c7cc9aed3a3/mzl.mlvhudjt.75x75-65.png",
  "vendor_identifier": "335060889",
  "ref_no": 335060889,
  "sku": "",
  "store_id": 1,
  "store": "apple",
  "release_date": "2009-12-17T00:00:00",
  "added_date": "2011-11-29T16:04:22",
  "updated_date": "2013-05-22T14:00:00",
  "version": "2.2.3",
  "source": null,
  "type": "unknown",
  "devices": [
    "Handheld",
    "Tablet"
  ],
  "price": {
    "currency": "USD",
    "price": "0.00"
  }
}
// GET /products/google_play/com.rdio.android.ui
{
  "id": 5555936,
  "name": "Rdio",
  "developer": "Rdio",
  "icon": "https://lh3.ggpht.com/L3w6B50SgmFOt8q_poF25XArA6EOJJSf7SOjBe9kPftnPVq8uS9JgtmJAwLVp_pN7ig",
  "vendor_identifier": "com.rdio.android.ui",
  "package_name": "com.rdio.android.ui",
  "store_id": 2,
  "store": "google_play",
  "release_date": "2000-01-02T00:00:00",
  "added_date": "2011-12-02T23:21:16",
  "updated_date": "2013-06-04T19:00:00",
  "version": "Varies with device",
  "source": null,
  "type": "unknown",
  "devices": [
    "Handheld"
  ],
  "price": {
    "currency": "USD",
    "price": "0.00"
  }
}
// GET /products/amazon/B004T76OR8
{
  "id": 212135374,
  "name": "Rdio",
  "developer": "Rdio",
  "icon": "http://ecx.images-amazon.com/images/I/51IPlKhP19L._SL160_SL150_.png",
  "vendor_identifier": "B004T76OR8",
  "package_name": "B004T76OR8",
  "store_id": 3,
  "store": "amazon_appstore",
  "release_date": "2000-01-01T00:00:00",
  "added_date": "2012-05-30T19:16:43",
  "updated_date": "2013-07-02T21:00:00",
  "version": "2.6.3",
  "source": null,
  "type": "unknown",
  "devices": [
    "Handheld"
  ],
  "price": {
    "currency": "USD",
    "price": "0.00"
  }
}

Listing all of your products

GET /products/mine/?store={store}

Scope

This resource requires the products:read scope.
store
(optional) Filter to only show products from a given store. apple, google_play, amazon_appstore are some valid examples. All available stores can be found by using the /data/stores route.

Request

GET /products/mine?store=apple

Example Response

// GET /products/212135374?store=apple
{
  "42": {
    "id": 42,
    "name": "Fob Finder Pro",
    "developer": "Consolidated Fob",
    "icon": "http://a4.mzstatic.com/us/r1000/030/Purple/75/f4/1a/mzl.fjpeofny.100x100-75.jpg",
    "vendor_identifier": "300101010",
    "ref_no": 300101010,
    "sku": null,
    "store_id": 1,
    "store": "apple",
    "release_date": "2008-11-15T05:00:00",
    "added_date": "2011-11-28T19:06:11",
    "updated_date": "2013-06-26T09:02:44",
    "version": "1.2",
    "source": {
      "external_account_id": 32,
      "added_timestamp": "2009-01-02T17:50:00",
      "active": true,
      "hidden": false,
      "type": "own"
    },
    "type": "unknown",
    "devices": [
      "Handheld",
      "Tablet"
    ],
    "children": [],
    "features": [],
    "parent_id": null,
    "price": {
      "currency": "USD",
      "price": "1.00"
    }
  },
   . . .
}

Updating products

Right now we only update you can make is changing the values of source.active and source.hidden to change how the product shows up in your account. It is an error to make this call on a product you don’t own.

Request

PUT /products/{product_id}

Scope

This resource requires the products:write scope.

Arguments (as json in request body)

source
Information about the origin of this product
active
Whether or not the product will import
hidden
Whether or not this product will show up in the UI

Example Request

// GET /products/31175

{
    id: 31175,
    name: "Plane Finder",
     . . .
    version: " 2.0.1 ",
    source: {
        external_account_id: 23830,
        added_timestamp: "2012-02-27T19:09:36",
        active: true,
        hidden: false,
        type: "own"
    },
     . . .
}
// PUT /external_accounts/31175

{
    id: 31175,
    source: {
        active: false,
        hidden: true,
    }
}

Example Response

// PUT /products/31175  with above request body

{
    id: 31175,
    name: "Plane Finder",
     . . .
    version: " 2.0.1 ",
    source: {
        external_account_id: 23830,
        added_timestamp: "2012-02-27T19:09:36",
        active: false,
        hidden: true,
        type: "own"
    },
     . . .
}

Getting Extra Product Metadata

The Public Data API add-on is required for this route.
Requests that include meta data always cost a credit. For routes that already cost a credit, adding meta=true will require an additional credit.

This isn’t a route so much as a setting that can be specified.

Most places you can be given products you can also ask for additional data from the products by appending the meta=true to your request. Passing this parameter adds two more entries to the product representation meta and categories.

Meta

The meta property is a collection of attributes grouped by language. The following attributes are currently available. More or different attributes may become available in the future.

  • description
  • developer_email
  • developer_site
  • downloads
  • name
  • rating
  • release_notes
  • view_url
  • download_size
  • company_url
  • support_url
  • artwork_url_large
  • artwork_url_small
  • bundle_identifier
  • copyright
  • itunes_version
  • primary_description
  • recommended_age
  • seller_name

Not all attributes are available for all products or stores. For instance, itunes_version is obviously Apple only, and downloads is Google Play only.

The full representation of the meta property will look like this:

 "meta": {
      "en": [
        {
          "key": "artwork_url_large",
          "language": "en",
          "value": "http://a3.mzstatic.com/us/r1000/010/Purple/31/a8/12/mzi.ixsiihjs.100x100-75.jpg"
        },
        {
          "key": "artwork_url_small",
          "language": "en",
          "value": "http://a2.mzstatic.com/us/r1000/012/Purple/05/1a/c0/mzi.hgvovgne.png"
        },
        {
          "key": "company_url",
          "language": "en",
          "value": "http://www.flyloopgame.com"
        },
        {
          "key": "copyright",
          "language": "en",
          "value": "© 2010 Spiralstorm Games Inc."
        },
        {
          "key": "description",
          "language": "en",
          "value": "********************************************Watch the video at www.flyloopgame.com********************************************New: Now supp *snip*"
        }
      ],
      "fr":{
         . . .
      }
      . . .
  }

Categories

The categories property is an array containing the categories the app is available for sale in currently or in has been in the past. The representation looks exactly like the representation described in Listing app store categories, with the addition of a property for showing whether or not this is the main category for the app. At this time only iOS and Mac apps support the main property.

The representation for categories looks like this:

    "categories": [
      {
        "store": "apple",
        "store_id": 1,
        "device": "handheld",
        "device_id": 1,
        "name": "Games",
        "id": 6014,
        "parent_id": null,
        "parent": null,
        "main": true
      },
      . . .
    ]

Example Response

// GET /products/search/embark?meta=true
[
  {
    "id": 6725579,
    "name": "Embark NYC Subway – New York City",
    "developer": "Embark, Inc.",
    "icon": "http://a1.mzstatic.com/us/r1000/101/Purple2/v4/75/17/1f/75171fa5-6f04-dca8-a439-f8b01bbec3e5/mzl.xxcfhuch.100x100-75.jpg",
    "vendor_identifier": "450991137",
    "ref_no": 450991137,
    "sku": "",
    "store_id": 1,
    "store": "apple",
    "release_date": "2011-07-31T00:00:00",
    "added_date": "2011-12-18T16:03:40",
    "updated_date": "2013-08-07T09:04:29",
    "version": "1.5.3",
    "source": null,
    "type": "unknown",
    "devices": [
      "Handheld",
      "Tablet"
    ],
    "price": {
      "currency": "USD",
      "price": "0.00"
    },
    "meta": {
      "en": [
        {
          "key": "description",
          "language": "en",
          "value": "Embark NYC Subway makes it easy to get around New York. Embark even works without cellular signal! Features: – Offline trip planning between subway stations – Interactive MTA Subway map – *snip*"
        },
        {
          "key": "view_url",
          "language": "en",
          "value": "http://itunes.apple.com/app/embark-nyc-subway-new-york/id450991137?uo=5"
        }
         . . .
      ]
    },
    "categories": [
      {
        "store": "apple",
        "store_id": 1,
        "device": "handheld",
        "device_id": 1,
        "name": "Travel",
        "id": 6003,
        "parent_id": null,
        "parent": null,
        "main": false
      },
      . . .
    ]
  }
  • http://stafox.ru/ Stafox

    Is it possible to get the price and currency for application’s in-app? I tried once, but api returns null for both.

  • Hennie Grobler

    Using api.appfigures.com/products/apple/368677368?client_key=xxx unexpectedly returns a 404. The apple app store id 368677368 is for Uber. Any pointers as to what I am doing wrong?

  • ng-Josh-H

    Is there any way to get urls to the screenshots that are available on the stores?

  • arturfornal

    One question, is “version” a optional key when I get informations from stores using “/v2/products/amazon/blabla” for example? Here is real url where lots of fields are missing (https://api.appfigures.com/v2/products/amazon/B015DBH9MW).

    • https://appfigures.com/ Alex Quick

      Thanks for pointing this out, we should have version information for all Amazon apps currently available in the store. We’ll look into why so many are missing.

      • Artur Fornal

        Ok, thanks!

  • Roi Semo

    I need to get “min os version” where can I get It?

  • Nikita Almakov

    Hello, I want to update products programmatically (via API, not https://appfigures.com/account/apps page) to make them active after I’ve added an external account. The API key, I’m using, has full API access rights. I’m still getting no apps with: GET /products/mine?store=apple

    What am I doing wrong? Please, help!

    • appfigures

      It’s hard to tell if anything is wrong with the setup or the account without more details. Please get in touch directly through the support page so we can take a closer look.

  • Yala

    Could you give an example on how to use filter? For example, to search for the apps in google play store that has “Facebook Messenger” in the name, I used: products/search/@name=Facebook Messenger?store=google_play

    But it returns all the apps, instead of the apps in google play. Am I missing something?

  • Yala

    How can I get product id? For example, if I want to get the reviews count for the Facebook app (iOS), where can I get the product id?

    • appfigures

      To get the ID you should use the /products/search/{keyword} route.

  • Brad Colbert

    The “store_name” property appears to now be called “store”, but is not reflected as such in the documentation above.

    • https://appfigures.com/ Alex Quick

      Hi, thanks for pointing this out. I’ll make sure the documentation gets updated.

  • pepepe

    Is there any way to know the languages availables for one application?

  • leotor

    I am unable to find a few of those meta attributes that you say are available. For example, I cannot find downloads &rating

    • alexquick

      Thanks for pointing this out. We only have that data for Google Play apps. I’ll make the documentation clearer.

  • Marc Schopper

    Why do you use different store identifiers: [apple, google_play, amazon_appstore] for GET /products/{store}/{id_in_store}

    [apple, google, amazon] for GET /products/mine/?store={store}

    • alexquick

      Good catch.

      Both sets of identifiers should work in both cases. The documentation for /products/mine shows old identifiers that still work for compatibility’s sake. I’ll make sure it gets updated.

  • Marc Schopper

    I tried GET /products/search/… API (with oauth authentication) but get a odd 403er. Is this route really only available with a Partner API access?

    {“status”: 403, “message”: “This resource requires Partner API Access. Reason: This route always requires Partner API Access and costs 0 credits.”, “additional”: “”, “reference”: “”}

    • appfigures

      That’s correct. You can enable this for free in your account by going to Account settings > Add-ons and enabling the Public Data Access add-on.

      Also, requests made to this route don’t cost any credits.

  • henry

    sometimes external_account_id is wrong. If I try to delete my external account and add it again, I will have a new external_account_id. But the products’ external_account_id aren’t updated accordingly

    • appfigures

      Products are updated once new data is imported and not when the account is linked.

  • PocketLogic

    What does the value “unknown” for product “type” indicate?

    • appfigures

      That’s an issue we’re working to resolve at this time.

  • Sean White

    Can you explain the ‘updated_date’ property in more detail? For instance, I have seen it change several times in the past few days without seeing any obvious differences in the other properties.

    When I first saw this, I was hoping it would be used to reflect when a product has been updated in the store.

    • appfigures

      That should be the expected behavior. Please get in touch directly if you noticed it isn’t with any of your apps.