Fields

data

paging

Validation Rules

Error

Description

100

Invalid parameter

200

Permissions error

Creating

Uploading Photos

There are two separate ways of publishing photos to Facebook:

1: Attach the photo as multipart/form-data. The name of the object doesn't matter, but historically people have used source as the parameter name for the photo. How this works depends on the SDK you happen to be using to do the post.

2: Use a photo that is already on the internet by publishing using the url parameter:

Parameters

Name

Description

aid

string

Legacy album ID. Deprecated

Deprecated

allow_spherical_photo

boolean

Default value: false

Indicates that we should allow this photo to be treated as a spherical photo. This will not change the behavior unless the server is able to interpret the photo as spherical, such as via Photosphere XMP metadata. Regular non-spherical photos will still be treated as regular photos even if this parameter is true.

application_id

non-empty string

iTunes App ID. This is used by the native Share dialog that's part of iOS

audience_exp

boolean

Default value: false

Audience exp

backdated_time

datetime

A user-specified creation time for this photo

backdated_time_granularity

enum{year, month, day, hour, min, none}

Default value: none

Use only the part of the backdated_time parameter to the specified granularity

caption

UTF-8 string

The description of the photo

Supports Emoji

composer_session_id

string

Composer session ID

direct_share_status

int64

The status to allow sponsor directly boost the post.

feed_targeting

feed target

Object that controls News Feed targeting for this post. Anyone in these groups will be more likely to see this post. People not in these groups will be less likely to see this post, but may still see it anyway. Any of the targeting fields shown here can be used, but none are required. feed_targeting applies to Pages only.

geo_locations

Object

countries

list<string>

regions

list<Object>

key

int64

cities

list<Object>

key

int64

zips

list<Object>

key

string

locales

list<string>

Values for targeted locales. Use type of adlocale to find Targeting Options and use the returned key to specify.

Array of integers which represent current educational status. Use 1 for high school, 2 for undergraduate, and 3 for alum (or localized equivalents).

interested_in

list<int64>

Indicates targeting based on the 'interested in' field of the user profile. You can specify an integer of 1 to indicate male, 2 indicates female. Default is all types. Please note 'interested in' targeting is not available in France due to local laws.

relationship_statuses

list<int64>

Array of integers for targeting based on relationship status. Use 1 for single, 2 for 'in a relationship', 3 for married, and 4 for engaged. Default is all types.

interests

list<int64>

One or more IDs of pages to target fans of pages.Use type of page to get possible IDs as find Targeting Options and use the returned id to specify.

full_res_is_coming_later

boolean

Default value: false

Full res is coming later

initial_view_heading_override_degrees

int64

Manually specify the initial view heading in degrees from 0 to 360. This overrides any value present in the photo embedded metadata or provided in the spherical_metadata parameter

initial_view_pitch_override_degrees

int64

Manually specify the initial view pitch in degrees from -90 to 90. This overrides any value present in the photo embedded metadata or provided in the spherical_metadata parameter

initial_view_vertical_fov_override_degrees

int64

Manually specify the initial view vertical FOV in degrees from 60 to 120. This overrides any value present in the photo embedded metadata or provided in the spherical_metadata parameter

is_explicit_location

boolean

Is this an explicit location?

is_explicit_place

boolean

If set to true, the tag is a place, not a person

manual_privacy

boolean

Default value: false

Manual privacy

message

UTF-8 string

Deprecated. Please use the caption param instead.

DeprecatedSupports Emoji

name

UTF-8 string

Deprecated. Please use the caption param instead.

DeprecatedSupports Emoji

no_story

boolean

If set to true, this will suppress the News Feed story that is automatically generated on a profile when people upload a photo using your app. Useful for adding old photos where you may not want to generate a story

offline_id

int64

Default value: 0

Offline ID

og_action_type_id

numeric string or integer

The Open Graph action type

og_icon_id

numeric string or integer

The Open Graph icon

og_object_id

OG object ID or URL string

The Open Graph object ID

og_phrase

string

The Open Graph phrase

og_set_profile_badge

boolean

Default value: false

Flag to set if the post should create a profile badge

og_suggestion_mechanism

string

The Open Graph suggestion

place

place tag

Page ID of a place associated with the photo

privacy

Privacy Parameter

Determines the privacy settings of the photo. If not supplied, this defaults to the privacy level granted to the app in the Login dialog. This field cannot be used to set a more open privacy setting than the one granted

profile_id

int

Deprecated. Use target_id instead

Deprecated

published

boolean

Default value: true

Set to false if you don't want the photo to be published immediately

qn

string

Photos waterfall ID

scheduled_publish_time

int64

Time at which an unpublished post should be published. Applies to Pages only

spherical_metadata

JSON object

A set of params describing an uploaded spherical photo. This field is not required; if it is not present we will try to generate spherical metadata from the metadata embedded in the image. If it is present, it takes precedence over any embedded metadata. Please click to the left to expand this list and see more information on each parameter. See also the Google Photo Sphere spec for more info on the meaning of the params: https://developers.google.com/streetview/spherical-metadata

--- In equirectangular projection: As described in Google Photo Sphere
XMP Metadata spec.

--- In cylindrical projection: Very similar to equirectangular.
This value should be equal to the actual width of the image, and
together with FullPanoWidthPixels, it describes the horizontal FOV
of content of the image: HorizontalFOV = 360 *
CroppedAreaImageWidthPixels / FullPanoWidthPixels.

--- In cubestrip projection: This has no relationship to the pixel
dimensions of the image. It is simply a representation of the
horizontal FOV of the content of the image.
HorizontalFOV = CroppedAreaImageWidthPixels / PixelsPerDegree,
where PixelsPerDegree is defined by FullPanoWidthPixels.

Required

CroppedAreaImageHeightPixels

integer

--- In equirectangular projection: As described in Google Photo Sphere
XMP Metadata spec.

--- In cylindrical projection: This value will NOT be equal to
the actual height of the image. Instead, together with
FullPanoHeightPixels, it describes the vertical FOV of the image:
VerticalFOV = 180 * CroppedAreaImageHeightPixels /
FullPanoHeightPixels. In other words, this value is equal to the
CroppedAreaImageHeightPixels value that this image would have, if it
were projected into equirectangular format while maintaining the
same FullPanoWidthPixels.

--- In cubestrip projection: This has no relationship to the pixel
dimensions of the image. It is simply a representation of the
vertical FOV of the content of the image.
VerticalFOV = CroppedAreaImageHeightPixels / PixelsPerDegree,
where PixelsPerDegree is defined by FullPanoWidthPixels.

Required

FullPanoWidthPixels

integer

--- In equirectangular projection: As described in Google Photo Sphere
XMP Metadata spec.

--- In cylindrical projection: Very similar to
equirectangular. This value defines a ratio of horizontal pixels to
degrees in the space of the image, and in general the pixel to degree
ratio in the scope of the metadata object. Concretely, PixelsPerDegree =
FullPanoWidthPixels / 360. This is also equivalent to the
circumference of the cylinder used to model this projection.

--- In cubestrip projection: This value has
no relationship to the pixel dimensions of the image. It only defines
the pixel to degree ratio in the scope of the metadata object. It
represents the number of pixels in 360 degrees, so pixels per degree
is then given by: PixelsPerDegree = FullPanoWidthPixels / 360. As an
example, if FullPanoWidthPixels were chosen to be 3600, we would have
PixelsPerDegree = 3600 / 360 = 10. An image with a vertical field of
view of 65 degrees would then have a CroppedAreaImageHeightPixels value
of 65 * 10 = 650.

Required

FullPanoHeightPixels

integer

--- In equirectangular projection: As described in Google Photo Sphere
XMP Metadata spec.

--- In cylindrical projection: This value is equal
to the FullPanoHeightPixels value that this image would have, if it
were projected into equirectangular format while maintaining the
same FullPanoWidthPixels. It is always equal to
FullPanoWidthPixels / 2.

--- In cubestrip projection: This value has
no relationship to the pixel dimensions of the image. It is a second,
redundant representation of PixelsPerDegree.
FullPanoHeightPixels = 180 * PixelsPerDegree. It must be consistent
with FullPanoWidthPixels:
FullPanoHeightPixels = FullPanoWidthPixels / 2.

Required

CroppedAreaLeftPixels

integer

--- In equirectangular projection: As described in Google Photo Sphere
XMP Metadata spec.

--- In cylindrical projection: This value is equal
to the CroppedAreaLeftPixels value that this image would have, if it
were projected into equirectangular format while maintaining the
same FullPanoWidthPixels. It is just a representation of the same
angular offset that it represents in equirectangular projection in the
Google Photo Sphere spec.
Concretely, AngularOffsetFromLeftDegrees = CroppedAreaLeftPixels /
PixelsPerDegree, where PixelsPerDegree is defined by
FullPanoWidthPixels.

--- In cubestrip projection: This value has
no relationship to the pixel dimensions of the image. It is just a
representation of the same angular offset that it represents in
equirectangular projection in the Google Photo Sphere spec.
AngularOffsetFromLeftDegrees = CroppedAreaLeftPixels / PixelsPerDegree,
where PixelsPerDegree is defined by FullPanoWidthPixels.

Required

CroppedAreaTopPixels

integer

--- In equirectangular projection: As described in Google Photo Sphere
XMP Metadata spec.

--- In cylindrical projection: This value is equal
to the CroppedAreaTopPixels value that this image would have, if it
were projected into equirectangular format while maintaining the
same FullPanoWidthPixels. It is just a representation of the same
angular offset that it represents in equirectangular projection in the
Google Photo Sphere spec.
Concretely, AngularOffsetFromTopDegrees = CroppedAreaTopPixels /
PixelsPerDegree, where PixelsPerDegree is defined by
FullPanoWidthPixels.

--- In cubestrip projection: This value has
no relationship to the pixel dimensions of the image. It is just a
representation of the same angular offset that it represents in
equirectangular projection in the Google Photo Sphere spec.
AngularOffsetFromTopDegrees = CroppedAreaTopPixels / PixelsPerDegree,
where PixelsPerDegree is defined by FullPanoWidthPixels.

Required

PoseHeadingDegrees

float

PosePitchDegrees

float

PoseRollDegrees

float

InitialViewHeadingDegrees

float

InitialViewPitchDegrees

float

InitialViewRollDegrees

float

This is not currently supported

InitialViewVerticalFOVDegrees

float

You can set the intial FOV of the image. Note that we support this
vertical FOV parameter, but InitialViewHorizontalFOV listed in the
Photo Sphere XMP Metadata spec is not currently supported

PreProcessCropLeftPixels

integer

PreProcessCropRightPixels

integer

sponsor_id

numeric string or integer

Facebook Page id that is tagged as sponsor in the photo post

sponsor_relationship

int64

Sponsor Relationship, such as Presented By or Paid PartnershipWith

tags

list<Object>

Tags on this photo

x

float

The x-axis offset for the tag

y

float

The y-axis offset for the tag

tag_uid

int

The user_id of the tagged person

tag_text

string

Text associated with the tag

target_id

int

Don't use this. Specifying a target_id allows you to post the photo to an object that's not the user in the access token. It only works when posting directly to the /photos endpoint. Instead of using this parameter you should be using the edge on an object directly, like /page/photos.

targeting

target

Allows you to target posts to specific audiences. Applies to Pages only

geo_locations

Object

countries

list<string>

regions

list<Object>

key

int64

cities

list<Object>

key

int64

zips

list<Object>

key

string

locales

list<string>

Values for targeted locales. Use type of adlocale to find Targeting Options and use the returned key to specify.