lauerfac.es - API Reference

Before you read on

• If you already have the number/id of a face and only want to display the image in your client, you don't need to use the API at all. Just add /full (for the full-sized image) or /thumb (for the thumbnail) to its URL to get it.
• Example:
• http://lauerfac.es/1/full
• http://lauerfac.es/1/thumb

Overview

• The API by default outputs JSON delivering all data about the faces stored at http://lauerfac.es
• (JSONP and XML output is also possibe, see below)
• The base URL for fetching data is http://lauerfac.es/api/

API Functionality

• There are four ways to get data from the API:

  • by id

    • The parameter id returns the face-data for the given id: Example 1
    • It also supports multiple comma-separated values: Example 2

  • by tag

    • The parameter tag returns the faces matching a given tag: Example 3

  • by category

    • Note: On lauerfac.es, there are no categories.

  • all

    • The parameter all returns a list of all tags or categories.
    • It accepts only two values, "cats" and "tags"
    • Get all categories: Example 5
    • Get all tags: Example 6

API Response

• Note: All code samples listed here are taken from ponyfac.es.

  So don't be confused about the values, the API itself is identical on both sites.

• Typical response

  • By default, the API returns JSON-encoded data, but you can also retrieve JSONP data or XML.
  • Compare these API-calls:
  • • http://lauerfac.es/api/id/1 (will output JSON) see result
    • http://lauerfac.es/api/id/1&callback=myJSONPcallback (will output JSONP) see result
    • http://lauerfac.es/api/id/1&out=xml (will output XML) see result
  All listed examples here are plain JSON, but you'll find links for the JSONP and XML versions along with each example. Comparing the output to JSON should be pretty self-explanatory.
  
  A typical JSON-response looks like this:

  {
    "unix_date":1311461814,
    "total_faces":"50",
    "total_views":"1234",
    "items":[
      {
        "face_id":"4",
        "face_views":"123",
        "face_hidden":0,
        "face_category":"twilight sparkle",
        "face_filename":"573f9ec2",
        "face_url":"http://ponyfac.es/faces/573f9ec2.png",
        "face_tags":"twilight sparkle, happy",
        "face_thumbnail":"http://ponyfac.es/thumbs/thumb_120_573f9ec2.png"
      }
    ]
  }

  Explained JSON-response:

  • unix_dateunix timestamp of the response
  • total_facestotal amount of stored faces on lauerfac.es
  • total_viewstotal amount of views on all single faces
  • itemsarray of faces
  •  → face_idID of the single face
  •  → face_viewspage-views of the face
  •  → face_hiddenshows if face is enabled or disabled
  •  → face_categorythe category of the face
  •  → face_filenamethe base-filename of the single face
  •  → face_urlthe absolute path to the fullsized face
  •  → face_tagsthe tags associated with the single face
  •  → face_thumbnailthe absolute path to the faces thumbnail image

Examples

• Example 1

  Requested URL: http://lauerfac.es/api/id/1  JSONP  XML
  JSON-response:

  {
    "unix_date":1311462196,
    "total_faces":"50",
    "total_views":"123",
    "items":[
      {
        "face_id":"1",
        "face_views":"4",
        "face_hidden":0,
        "face_category":"pinkie pie",
        "face_filename":"3cc43dc9",
        "face_url":"http://ponyfac.es/faces/3cc43dc9.gif",
        "face_tags":"pinkie pie, happy, clap",
        "face_thumbnail":"http://ponyfac.es/thumbs/thumb_120_3cc43dc9.png"
      }
    ]
  }

• Example 2

  Requested URL: http://lauerfac.es/api/id/23,42  JSONP  XML
  JSON-response:

  {
    "unix_date":1311462567,
    "total_faces":"50",
    "total_views":"1234",
    "items":[
      {
        "face_id":"23",
        "face_views":"10",
        "face_hidden":0,
        "face_category":"twilight sparkle",
        "face_filename":"88ef730a",
        "face_url":"http://ponyfac.es/faces/88ef730a.jpg",
        "face_tags":"twilight sparkle",
        "face_thumbnail":"http://ponyfac.es/thumbs/thumb_120_88ef730a.png"
      },
      {
        "face_id":"42",
        "face_views":"20",
        "face_hidden":0,
        "face_category":"fluttershy",
        "face_filename":"182465be",
        "face_url":"http://ponyfac.es/faces/182465be.jpg",
        "face_tags":"fluttershy",
        "face_thumbnail":"http://ponyfac.es/thumbs/thumb_120_182465be.png"
      }
    ]
  }

• Example 3

  Requested URL: http://lauerfac.es/api/tag/happy  JSONP  XML
  JSON-response:

  {
    "unix_date":1311463199,
    "total_faces":"50",
    "total_views":"1234",
    "items":[
      {
        "face_id":"1",
        "face_views":"4",
        "face_hidden":0,
        "face_category":"pinkie pie",
        "face_filename":"3cc43dc9",
        "face_url":"http://ponyfac.es/faces/3cc43dc9.gif",
        "face_tags":"pinkie pie, happy, clap",
        "face_thumbnail":"http://ponyfac.es/thumbs/thumb_120_3cc43dc9.png"
      },
      {
        "face_id":"3",
        "face_views":"16",
        "face_hidden":0,
        "face_category":"rainbow dash",
        "face_filename":"80b6d653",
        "face_url":"http://ponyfac.es/faces/80b6d653.gif",
        "face_tags":"rainbow dash, happy, lol",
        "face_thumbnail":"http://ponyfac.es/thumbs/thumb_120_80b6d653.png"
      },
      {
        "face_id":"12",
        "face_views":"4",
        "face_hidden":0,
        "face_category":"fluttershy",
        "face_filename":"a476808d",
        "face_url":"http://ponyfac.es/faces/a476808d.png",
        "face_tags":"fluttershy, happy",
        "face_thumbnail":"http://ponyfac.es/thumbs/thumb_120_a476808d.png"
      }
    ]
  }

• Example 4

  Requested URL: http://lauerfac.es/api/cat/fluttershy  JSONP  XML
  JSON-response:

  {
    "unix_date":1311464018,
    "total_faces":"50",
    "total_views":"1234",
    "items":[
      {
        "face_id":"12",
        "face_views":"4",
        "face_hidden":0,
        "face_category":"fluttershy",
        "face_filename":"a476808d",
        "face_url":"http://ponyfac.es/faces/a476808d.png",
        "face_tags":"fluttershy, happy",
        "face_thumbnail":"http://ponyfac.es/thumbs/thumb_120_a476808d.png"
      },
      {
        "face_id":"14",
        "face_views":"27",
        "face_hidden":0,
        "face_category":"fluttershy",
        "face_filename":"2612bf13",
        "face_url":"http://ponyfac.es/faces/2612bf13.jpg",
        "face_tags":"fluttershy",
        "face_thumbnail":"http://ponyfac.es/thumbs/thumb_120_a476808d.png"
      }
    ]
  }

• Example 5

  Requested URL: http://lauerfac.es/api/all/cats  JSONP  XML
  JSON-response:

  {
    "unix_date":1311612197,
    "items":[
      {
        "cat_id":1,
        "cat_name":"all",
        "cat_displayname":"All Ponies"
      },
      {
        "cat_id":2,
        "cat_name":"rainbowdash",
        "cat_displayname":"Rainbow Dash"
      },
      [...]
      {
        "cat_id":8,
        "cat_name":"other",
        "cat_displayname":"Other Ponies"
      }
    ]
  }

  Explained JSON-response:
  • unix_dateunix timestamp of the response
  • itemsarray holding all categories
  •  → cat_idunique ID of the category
  •  → cat_namelowercase category name without spaces.
  •  → cat_displaynamefull name of the category with spaces and other special characters

• Example 6

  Requested URL: http://lauerfac.es/api/all/tags  JSONP  XML
  JSON-response:

  {
    "unix_date":1311612476,
    "items":[
      {"tag_name":"pinkie pie"},
      {"tag_name":"happy"},
      {"tag_name":"clap"},
      {"tag_name":"sweetie belle"},
      {"tag_name":"tongue"},
      {"tag_name":"taunt"},
      {"tag_name":"tease"},
      {"tag_name":"rainbow dash"},
      {"tag_name":"lol"}
    ]
  }

  Explained JSON-response:
  • unix_dateunix timestamp of the response
  • itemsarray holding all tags
  •  → tag_namelowercase tag name.