Parameters

This section contains the possible request parameters.

Version

http://api.pinkvisual.com/get/<latest>/...

Each request has a version parameter in its URL (emboldened as “latest” in the example above). PVAPI currently has only one version, the “latest” version. However, this parameter is provided in the event that some future change requires PVAPI to change a request, its returned data, or some other part of the system. In that event, you will be able to use the version parameter to specify an older version of the request.

You should always prefer to use the “latest” version. This is currently an alias for “1.0”, and you may choose to use “1.0” as your version if you want to ensure no request ever changes in a way that breaks your code.

In some cases, PVAPI may make upgrades or tweaks to the system that will not affect your code. For example, new data may be added, or the search algorithm altered. In cases like this, PVAPI will not create a new real version number. This function is reserved only for the rare changes that break backwards-compatibility.

Start

In order to facilitate pagination, you can pass the start parameter to most requests. This indicates where, out of the total data set, to begin fetching.

All requests have a default “start” of zero (0).

API keys that are in the “development” stage will have an enforced start value. You can remove this limit by getting your site or application approved.

Use

Add &start=X to any API request, where X is an integer and is the item to start on.

If you are showing 10 items per page, page 1 is start=0 and page 2 is start=10.

If you are showing 10 items per page, page 1 is start=0 and page 2 is start=10.

Limit

The limit parameter determines the number of items to fetch. When combined with “start”, this is the mechanism for pagination.

Most requests default to “no limit”.

Some requests have an enforced maximum limit. In this case, you can still pass any limit without receiving an error. You will only receive the maximum number allowed, and the “limit” entry in the returned data will be changed.

API keys that are in the “development” stage will also have an enforced limit. You can remove this limit by getting your site or application approved.

Use

Add &limit=X to any API request, where X is an integer and the number of items to fetch.

If you’re showing 10 items per page, pass limit=10.

If you want all items, pass limit=-1 (negative 1) or omit this limit.

Tips

If you only need to know the total number of objects, you can make a request with limit=0. The returned data will still include the “total” entry as normal.

Sort

Many requests can be organized with the sort parameter. For example, if you want to show the hottest episodes, sort by rating.

Valid sort options

The following sorts are recognized by many API requests:

  • name - Sort by episode/model/niche name.
  • date - Sort by newest (episodes only).
  • rating - Sort by rating (episodes only).
  • relevance - Sort by relevance (search only).
  • random - Random order for the results.

Use

Add &sort=X to any request, where X is the name of a sort option.

Add &sort=X to any request, where X is the name of a sort option.

Filters

You can restrict types of data by using the filter option. For example, if your site shows only gay porn, you should pass the “gay” filter.

Note: You can set default filters in your Settings page.

Valid filters

You can pass any of these filters:

  • Orientation filters (mainly for Episodes):
  • straight (s)
  • gay (g)
  • tranny (t)
  • Gender filters (only for Actors):
  • male (m)
  • female (f)
  • tranny (t)

Use

Filter your results by putting &filter=X in the API request URL, where X is either the full name (“gay”) or short name (“g”) of a filter, above.

You can use more than one filter by comma-separating them in the request: filter=straight,tranny (or filter=s,t)

If you pass no filters, you receive unfiltered content. If you pass at least 1 filter, you receive only the content requested by the filter.

If you pass no filters, you receive unfiltered content. If you pass at least 1 filter, you receive only the content requested by the filter.

Mode

The mode parameter specifies what format you’d like to receive data in. You can choose a default mode in your Settings page, but you can also override that with this parameter.

Valid Modes

  • json - Receive data in the Javascript Object Notation format. This is a simple, human-readable format.
  • xml - Recevie data in the Extensible Markup Language. This is more complicated than json, but we know some developers prefer XML.

Use

You can request a data mode by putting &mode=xml or &mode=json in your request URLs. If you omit this parameter, it will default to the one you chose on your Settings page.

Project Versions

Table Of Contents

Previous topic

Implementation Notes

Next topic

Data Types

This Page