Products

Use /products to look up product metadata by Appfigures ID or store ID, search for products, and list or update your own.

What Is a Product

A product is anything you can track in Appfigures. Usually it’s an app, but it can also be an in-app purchase (IAP) or a book.

We collect product data directly from the store that sells the product. These properties are available for all products, including ones that aren’t owned by or shared with your account.

Field	Type	Description
id	Number	The product’s Appfigures-assigned ID.
name	string	Full name of the product.
developer	string	The developer’s name.
icon	string	URL to the product’s icon on the store.
vendor_identifier	string	The ref_no or SKU the store uses to uniquely identify this product.
ref_no	int	The product’s store ID, if available. Currently applies only to Apple apps.
sku	string	The developer-assigned SKU or package name.
store_id	int	ID of the store that sells this product.
store	string	Name of the store that sells this product. Options: “apple”, “google_play”, etc. The full list of stores is available at /data/stores.
release_date	date	The date the product was released to the store.
added_date	date	Date we added the product to Appfigures.
updated_date	date	Date we last updated the product.
version	string	The product’s current version.
type	string	Type of product. Options: “app”, “inapp”, “book”.
devices	array	Devices the product is sold for. Options: “Handheld” (e.g. iPhone), “Tablet” (e.g. iPad), “Desktop”.
active	bool	Whether the product is active in the store.

Products owned by or shared with your account also include these account-specific properties:

Field	Type	Description
parent_id	int	For an in-app purchase, the product ID of the parent product.
children	array	If this product has in-app purchases, a list of their product IDs.
features	array	Additional features the product supports. Options: iads, admob.
source	object	Information describing the product within your Appfigures account: 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 in your Appfigures account. hidden Whether the product is hidden from 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 Appfigures ID

GET /products/{id}

Field	Type	Description
id	Number	The Appfigures-assigned ID of the product you want.

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

Caution

This route requires the Public Data API add-on.

Note

Scope: This resource requires the public:read scope.

Request

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

Arguments

Note: filter is deprecated. Use storefronts instead.

Field	Type	Description
term	String	The name of a product or developer. Prefix with @name= or @developer= to search only that field.
filter (deprecated)	String	Filter to apply to the results: one of ios, mac, google, amazon. Defaults to all results.
storefronts	String	Semicolon-separated set of storefronts to filter the results by. apple, apple:mac, google_play, amazon_appstore, and windows10 are some valid examples. Get the full list of storefronts from the /data/stores route.
page	Number	Page of results to show. Defaults to the first page.
count	Number	Number of results per 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}

Argument	Description
store	The store the product is from. Valid examples: apple, google_play, amazon_appstore. Get the full list of stores from the /data/stores route.
id_in_store	The product’s unique identifier in the store: Apple ID for iOS and Mac apps, SKU for Google Play, and ASIN for Amazon Appstore apps.

Note

If you request a product that isn’t in our database, we look it up in the store in real time. This happens automatically for all stores.

Some stores take longer than others. We wait up to 90 seconds for the lookup. If we find the product in that time, we return it.

If the lookup is still running after 90 seconds, it continues in the background and you’ll get a 202 response with a URL to check its status.

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}&include_inactive={true|false}

Note

Scope: This resource requires the products:read scope.

Field	Type	Description
store	String	Show only products from this store. Valid examples: apple, google_play, amazon_appstore. Get the full list of stores from the /data/stores route.
include_inactive	Boolean	Whether to include inactive products. Defaults to false, so we don’t return inactive products.

Request

GET /products/mine?store=apple

Example Response

// GET /products/mine?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

You can change source.active and source.hidden to control how the product shows up in your account. Those are the only updates we support right now. You’ll get an error if you make this call on a product you don’t own.

Request

PUT /products/{product_id}

Note

Scope: This resource requires the products:write scope.

Arguments (as JSON in Request Body)

Field	Type	Description
source	String	Information about the origin of this product. - active - Whether the product will import - hidden - Whether the 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 /products/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

Caution

This route requires the Public Data API add-on.

Caution

Adding meta=true will require five additional credits.

This is a setting, not a route. Most places that return products also accept meta=true. It adds two entries to each product: meta and categories.

Meta

The meta property is a collection of attributes grouped by language. These attributes are available now. We may add or change attributes 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 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 of the categories the app is in now or has been in before. Each entry matches the representation in Listing app store categories, plus a main property that shows whether it’s the app’s main category. Only iOS and Mac apps support main right now.

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
      },
      . . .
    ]
  }
]