Search.byfields

From Safe Creative API
Revision as of 08:47, 14 May 2010 by w>Jguillo
Jump to navigation Jump to search

Search for works specifying which fields of the work to search under.

If you specify several fields, returned works will match all conditions.

Results are paginated

Info

  • Component name: search.byfields
  • Signature: No signature required
  • Timestamp: Ztime is not required
  • API trust level: Public
  • API server: http://api-search.safecreative.org

Parameters

  • fieldN: Field to search. You can search in various fields. N must be a number 1..n.
  • valueN: Value of fieldN. Fields and values must match.
  • page: Page number
  • locale: Locale for work type, license names,...

* Required parameter

Supported fields

  • code: Work code
  • name: Work title
  • excerpt: Work summary
  • user.name: Author or rights holder name
  • user.code: Author or rights holder code
  • allowDownload: Work can be downloaded (true|false)
  • allowRightsRequests: Work rights holders can be asked for permission to use the work (true|false)
  • tag: Work tags. You can specify more than one tag repeating the field with different values
  • license.code: Work license code (see user.licenses)
  • license.name: Work license name
  • license.shortName: Work license abbrevation
  • workType.code: Work type code (see work.types)
  • workType.name: Work type name
  • workTypeGroup.code: Work type group code (see work.types.tree)
  • workTypeGroup.name: Work type group name

Returns

Paginated list of work elements

  • work
    • code: Safe Creative work code
    • title: Work title
    • authors: List of authors
      • author
        • code: Author's Safe Creative user code
        • name: Author's full name
        • human-url: URL to the author's Safe Creative public profile
    • rights-holders: List of rights holders
      • rights-holder
        • code: Rights holder's Safe Creative user code
        • name: Rights holder's full name
        • human-url: URL to the rights holder's Safe Creative public profile
    • thumbnail: URL to the work thumbnail (if any)
    • license: Work license
      • code: License code
      • name: License name
      • shortname: License short name
      • human-url: URL to license text
      • features: License features (see user.licenses
    • human-url: URL to this work web page in Safe Creative
    • machine-url: URL to this work API info response (see work.get)

Example

REQUEST (searching for photographs under a Creative Common license which can be downladed):

https://search.safecreative.org/v2/
?component=search.byfields
&field1=workType.code
&value1=photo
&field2=license.name
&value2=Creative+Commons
&field3=allowDownload
&value3=true

RESPONSE:

<?xml version="1.0" encoding="UTF-8"?>
<listpage>
  <recordtotal>9274</recordtotal>
  <pagetotal>371</pagetotal>
  <list>
    <work>
      <code>0910064634779</code>
      <title>rejas azules ventana amarilla</title>
      <authors>
        <author>
          <code>0909290055601</code>
          <name>Olatz Garcia Relloso</name>
          <human-url>http://www.safecreative.org/user/0909290055601</human-url>
        </author>
      </authors>
      <rights-holders>
        <rights-holder>
          <code>0909290055601</code>
          <name>Olatz Garcia Relloso</name>
          <human-url>http://www.safecreative.org/user/0909290055601</human-url>
        </rights-holder>
      </rights-holders>
      <thumbnail>https://thumbnails-safecreative-org.s3.amazonaws.com/1/00000124/2948/76f9/510b/c6b91a9412ad/rejasazulesventanaamarilla_thumb.png</thumbnail>
      <license>
        <code>http://creativecommons.org/licenses/by-nc-nd/3.0/</code>
        <name>Creative Commons Attribution Non-commercial No Derivatives 3.0</name>
        <shortname>CC by-nc-nd</shortname>
        <human-url>http://creativecommons.org/licenses/by-nc-nd/3.0/legalcode</human-url>
        <features>
          <timelimited>NOT_APPLICABLE</timelimited>
          <recognition>YES</recognition>
          <distribution>YES</distribution>
          <derivations>NO</derivations>
          <commercial>NO</commercial>
        </features>
      </license>
      <human-url>http://www.safecreative.org/work/0910064634779</human-url>
      <machine-url>http://www.safecreative.org/v2/?component=work.get&code=0910064634779</machine-url>
    </work>
    [...]
    <work>
      <code>1002105501801</code>
      <title>cora3115</title>
      <authors>
        <author>
          <code>1002100124746</code>
          <name>tanita</name>
          <human-url>http://www.safecreative.org/user/1002100124746</human-url>
        </author>
      </authors>
      <rights-holders>
        <rights-holder>
          <code>1002100124746</code>
          <name>tanita</name>
          <human-url>http://www.safecreative.org/user/1002100124746</human-url>
        </rights-holder>
      </rights-holders>
      <thumbnail>https://thumbnails-safecreative-org.s3.amazonaws.com/1/00000126/b931/9979/9ae8/23845be4ebcc/dscf3115_thumb.png</thumbnail>
      <license>
        <code>http://creativecommons.org/licenses/by-nc/3.0/</code>
        <name>Creative Commons Attribution Non-Commercial 3.0</name>
        <shortname>CC by-nc</shortname>
        <human-url>http://creativecommons.org/licenses/by-nc/3.0/legalcode</human-url>
        <features>
          <timelimited>NOT_APPLICABLE</timelimited>
          <recognition>YES</recognition>
          <distribution>YES</distribution>
          <derivations>YES</derivations>
          <commercial>NO</commercial>
        </features>
      </license>
      <human-url>http://www.safecreative.org/work/1002105501801</human-url>
      <machine-url>http://www.safecreative.org/v2/?component=work.get&code=1002105501801</machine-url>
    </work>
  </list>
</listpage>