Domain API overview Request Access

Welcome! We're excited to share our new Domain API endpoints, which are great for helping people discover content on your site.

There are all sorts of uses for these APIs. You could surface your domain's most clicked-through or most repinned Pins, letting your visitors see the content that's most popular with Pinners. Or, you could use the Related Pins API to offer recommendations or suggested content on your domain. Want to show pins that are from a certain category? Check out our Domain Search API. These are just a few of the ways partners are starting to use our domain APIs on their websites and mobile apps.

These API endpoints are available for domains that are verified and belong to your Pinterest account.

Overview

The domain API is a restful, json speaking API. All responses are either json or jsonp.

  • Filtering

    The API filters out all things belonging to inactive users so you don't have to. Data returned by the API will be free of unwanted users and spam content.
  • Response type formats

    When viewing items in lists, the API defaults to a summary of relevant fields. This is a subset of the fields that you'll see when viewing a single item. When viewing an item in isolation, you'll see all of the fields associated with that item.

  • Specifying response fields

    You can select a subset of fields to return on a type. The syntax follows: fields=pin.first_name,pin.last_name In the above example, pins will only include first_name and last_name.
  • Adding fields to a summary

    You can customize the fields in a specific response type, by using the add_fields parameter to augment the default field list with any field you specify.

    For example, If you want to add the first_name field to a pin, do the following: add_fields=pin.first_name You can add several fields to several object types as well: add_fields=pin.first_name,pin.last_name,board.title

  • Images

    Some return types have an images attribute. This attribute is not included as part of a summary view, and must be specifically requested. However, sending back all the images would be overkill for most instances, so when you request this field, you must provide all of the image keys you require.

    An image key is just the width and height of an image joined by an 'x'. For example: 64x64. Some keys specify only the width, since the height will be affected by the aspect ratio of the original image. For images of this type, only the width is provided, like 1200x.

    To request multiple images, use the following syntax:
    pin.images=[64x64,75x75,1200x]

    This will cause the response to have an 'images' key like this:

    {
    'id': "12345",
    'type': "pin",
    
    'images': {
    
       '64x64': {
            'width': 64,
            'height': 64,
            'url': "http://..../a4c3b12cffaa.jpg"
        },
    
        '75x75': {
           'width': 75,
           'height': 75,
           'url': "http://..../a4c3b12cffaa.jpg"
        }
    
        '1200x': {
            'width': 625,
            'height': 417,
            'url': "http://.../a4c3b12cffaa.jpg
        }
    
    }
    }

    Note that the actual image size can be smaller than the size that corresponds to the image key. This is because the original image was smaller than the image key, and Pinterest doesn't scale images larger than their original size.

  •  

    Bookmarks

    For some queries that return long lists of items, the API will respond with a bookmark. Echoing this bookmark back to the same call on a subsequent request will resume where you left off. bookmark=<really long string>
  • Response types

    Appending a query string param of 'callback' will make the API respond with jsonp wrapped in a function call. The function's name is the value of the callback parameter.