Search.byfields: Difference between revisions

From Safe Creative API
Jump to navigation Jump to search
w>Jguillo
(Created page with '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 responses…')
 
w>Jguillo
No edit summary
Line 65: Line 65:


= Sample =
= Sample =
REQUEST (searching for ''"Creative Commons" music'':
REQUEST (searching for photographs under a Creative Common license which can be downladed):


  <nowiki>https://search.safecreative.org/v2/</nowiki>
  <nowiki>https://search.safecreative.org/v2/</nowiki>

Revision as of 08:38, 6 May 2010

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)

Sample

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>