Customizing Response Fields

 

ON THIS PAGE      Show

 

 

 

 

Required vs. Default Fields

API responses always include certain metadata fields when available and applicable. Attempting to exclude these fields from responses results in an error.

These required fields are marked as ("May not be excluded") in Content Metadata Field Definitions. In addition to the required fields, the API returns a default set of fields in the Search and Feed responses.

All available fields are returned by default in the Item Metadata, Account Plans and Account Download History responses.

Including and Excluding Fields

You can use one or more of the following parameters to customize the returned fields:

  • include. One or more comma-separated fields to include in the response in addition to the required fields (NOT in addition to the default fields); for example, include=signals or include=subject,place,organisation,person.

    • include=* returns all available fields.

    • include=view_default,<field_name> returns the default fields plus your own list; for example:

      include=view_default,subject returns the default fields plus subject

    • include=*.<field_name> returns every field with a specific attribute; for example:

      include=*.title returns photographer.title, renditions.main.title, renditions.preview.title and renditions.thumbnail.title for pictures

    • include=<field_path> returns a specific field; for example:

      subject.code or renditions.thumbnail.href

    • Using * to replace characters in the field name (for example, include=description_*) is NOT supported.

    • On the individual item metadata request, you can reference include=view_default_searchDisplay to get the default fields returned by the Search method; for example, when just updating a previous search result.

  • exclude. One or more comma-separated fields to exclude from the set of fields specified by the include parameter (or from a default set of fields if no include parameter is specified); for example, exclude=datelinelocation.

    • exclude=* excludes every content item metadata field except the required fields and those specified in the value of the include parameter; for example:

      include=renditions.main,datelinelocation,subject&exclude=* excludes all fields except the fields that may not be excluded and renditions.main, datelinelocation and subject.

    • exclude=*.<name> excludes every field with a specific attribute; for example:

      exclude=*.code excludes all fields with the code attribute

    • exclude=<field_path> excludes a specific field; for example, subject.code or renditions.main.originalfilename.

    • Using * to replace characters in the field name (for example, exclude=description_*) is NOT supported.