▣ GEOLOCATION · STANDARD DATA

Find & Compare Film Festivals Around the World

What it does

Festival Listings gives you searchable data on festivals, their categories, countries, deadlines, dates, fees, and roster details.

Use the list endpoints to browse festivals with filters for q, genre, state, country, fee_max, category, deadline_after, deadline_before, event_date_before, and submission_platform. You can also sort by name, deadline, or event_date, and page through results with page and per_page. Each festival summary includes fields such as id, name, country, categories, genres, plus optional metadata like city, state, website, event_dates, regular_fee, deadline_regular, deadline_late, event_start_date, composite_score, and submission_platforms.

If you need a single record, fetch festival detail by id to get the full festival object, including description, fees, accepts_awards, acceptance_rate, year_founded, deadline_extended, notification_date, past_winners, and programming_directors when available. For ranking workflows, the top-scored festivals endpoint returns the same festival summary shape ordered by score.

The country and category endpoints help you build filters and navigation from the dataset itself. The festival roster endpoint returns results for a given festival id, with film-level fields like film_title, film_year, film_award, film_genre, film_category, and film_director. That makes Festival Listings useful for festival discovery tools, submission trackers, awards research, and content databases.

▣ ENDPOINT 01 / 06

GET

List available countries

http://localhost:8080/ryanvinson/film-festivals-around-world/festival/countries

QUICKSTARTGUIDE

Quickstart

This GET request fetches the festival count summary.

curl -X GET "http://localhost:8080/ryanvinson/film-festivals-around-world/festival/countries" \
  -H "apy-token: $APY_TOKEN"

What you'll get back

Returns a JSON object with a count integer and a results array. Each item in results is an object with a country string and a festival_count integer.

{
  "count": 2,
  "results": [
    {
      "country": "India",
      "festival_count": 24
    },
    {
      "country": "Japan",
      "festival_count": 15
    }
  ]
}

TRY ITLIVE · 1 ATOM

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Returns a JSON object with a count integer field and a results array field. Each item in results is an object describing a country and its associated festival_count.

Response

Returns a JSON object with a count integer field and a results array of objects. Each object in results contains a country string and a festival_count integer.

Parameter	Type	Mandatory	Description
count	Integer	Yes	Total number of items returned in `results`.
results	Object Array	Yes	Array of country objects. Each item contains:<br>- `country`: string<br>- `festival_count`: integer

Parameters

No parameters.

▣ ENDPOINT 02 / 06

GET

List categories

http://localhost:8080/ryanvinson/film-festivals-around-world/categories

QUICKSTARTGUIDE

Quickstart

Make a simple GET request to fetch the endpoint’s JSON response.

curl -X GET "http://localhost:8080/ryanvinson/film-festivals-around-world/categories" \
  -H "apy-token: $APY_TOKEN"

What you'll get back

Returns a JSON object with:

count (integer): the total count value.
results (array): an array of objects, each with:
- count (integer)
- category (string)

{
  "count": 29,
  "results": [
    {
      "category": "short_film",
      "count": 2291
    },
    {
      "category": "feature",
      "count": 1655
    },
    {
      "category": "documentary",
      "count": 1241
    },
    {
      "category": "music",
      "count": 4
    },
    {
      "category": "vertical",
      "count": 3
    },
    {
      "category": "thriller",
      "count": 3
    },
    {
      "category": "design",
      "count": 2
    },
    {
      "category": "games",
      "count": 2
    },
    {
      "category": "dance",
      "count": 1
    },
    {
      "category": "fashion",
      "count": 1
    },
    {
      "category": "romance",
      "count": 1
    }
  ]
}

TRY ITLIVE · 1 ATOM

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Returns a JSON object containing a total count and a results array of category objects.

Response

Returns a JSON object with a count integer field and a results array field. Each item in results is an object with count and category fields.

Parameter	Type	Mandatory	Description
count	Integer	Yes	Total count returned by the endpoint.
results	Object Array	Yes	Array of category objects. Each item contains:<br>- `count` (`Integer`): Count associated with the category.<br>- `category` (`String`): Category name.

Parameters

No parameters.

▣ ENDPOINT 03 / 06

GET

List film festivals

http://localhost:8080/ryanvinson/film-festivals-around-world/festivals/list

QUICKSTARTGUIDE

Quickstart

Fetch a page of results, optionally filtered by query parameters.

curl -X GET "http://localhost:8080/ryanvinson/film-festivals-around-world/festivals/list" \
  -H "apy-token: $APY_TOKEN"

What you'll get back

Returns a JSON object with count, page, per_page, total_pages, and results fields. results is an array of objects, each containing required id, name, country, categories, and genres fields, plus other fields when present.

{
  "count": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1,
  "results": [
    {
      "id": 123,
      "name": "Spring Design Awards",
      "country": "US",
      "categories": ["Design"],
      "genres": ["Graphic Design"]
    }
  ]
}

TRY ITLIVE · 1 ATOM

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Returns a paginated list of festivals filtered by the optional query parameters. The response includes paging metadata plus an array of festival objects.

Query Parameter(s)

Attribute	Type	Mandatory	Description
q	String	No	Search query string.
page	Integer	No	Page number. Default: `1`.
sort	ENUM	No	Sort order. Allowed values: `name`, `deadline`, `event_date`.
genre	String	No	Filter by genre.
state	String	No	Filter by state.
country	String	No	Filter by country.
fee_max	Number	No	Maximum fee value.
category	String	No	Filter by category.
per_page	Integer	No	Number of results per page. Default: `20`. Maximum: `100`.
deadline_after	String	No	Filter by deadlines on or after this date. Format: `date`.
deadline_before	String	No	Filter by deadlines on or before this date. Format: `date`.
event_date_before	String	No	Filter by event dates on or before this date. Format: `date`.
submission_platform	String	No	Filter by submission platform.

Response

Returns a JSON object with page and count integers, a per_page integer, a total_pages integer, and a results array of festival objects. Each festival object includes the required fields id (integer), name (string), country (string), categories (string array), and genres (string array), plus optional detail fields.

Parameter	Type	Mandatory	Description
page	Integer	Yes	Current page number.
count	Integer	Yes	Number of results returned in the response.
per_page	Integer	Yes	Results per page.
total_pages	Integer	Yes	Total number of pages available.
results	Object Array	Yes	Array of festival objects. Each item includes `id`, `name`, `country`, `categories`, and `genres` as required fields.

Query parameters

Name

Type

Description

qOPTIONAL

string

—

pageOPTIONAL

integer

—

DEFAULT 1

sortOPTIONAL

string

name · deadline · event_date

—

genreOPTIONAL

string

—

stateOPTIONAL

string

—

countryOPTIONAL

string

—

fee_maxOPTIONAL

number

—

categoryOPTIONAL

string

—

per_pageOPTIONAL

integer

—

DEFAULT 20

deadline_afterOPTIONAL

string

—

deadline_beforeOPTIONAL

string

—

event_date_beforeOPTIONAL

string

—

submission_platformOPTIONAL

string

—

▣ ENDPOINT 04 / 06

GET

Get film festival detail

http://localhost:8080/ryanvinson/film-festivals-around-world/festival/detail/:id

QUICKSTARTGUIDE

Quickstart

Fetch the festival record for a specific ID by putting the required path parameter in the URL.

curl -X GET "http://localhost:8080/ryanvinson/film-festivals-around-world/festival/detail/:id" \
  -H "apy-token: $APY_TOKEN"

What you'll get back

Returns a JSON object with the required id, name, country, categories, and genres fields, plus additional optional fields when available.

{
  "id": 123,
  "name": "Sundance Film Festival",
  "country": "United States",
  "categories": ["Film"],
  "genres": ["Drama"]
}

TRY ITLIVE · 1 ATOM

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Retrieves the details for a single festival identified by its path id. The response is a JSON object containing the festival’s core metadata, dates, categories, genres, and related fields defined in the output schema.

Path Parameter(s)

Attribute	Type	Mandatory	Description
id	Integer	Yes	Festival identifier in the path.

Response

Returns a JSON object with required fields id (integer), name (string), country (string), categories (array of strings), and genres (array of strings), along with the optional festival metadata fields declared in the schema.

Parameter	Type	Mandatory	Description
id	Integer	Yes	Festival identifier.
city	String	No	City associated with the festival.
fees	Object	No	Fee information. Nullable.
name	String	Yes	Festival name.
year	Integer	No	Festival year. Nullable.
state	String	No	State associated with the festival.
genres	String Array	Yes	Genre labels for the festival.
country	String	Yes	Festival country.
website	String	No	Festival website URL. Format: URI.
categories	String Array	Yes	Festival categories.
description	String	No	Festival description.
event_dates	String	No	Event dates as a string.
past_winners	Object Array	No	Past winners. Nullable; item shape is not defined in the schema.
year_founded	Integer	No	Year the festival was founded. Nullable.
deadline_late	String	No	Late deadline date. Format: date. Nullable.
accepts_awards	Boolean	No	Whether the festival accepts awards.
event_end_date	String	No	Event end date. Format: date. Nullable.
acceptance_rate	Number	No	Acceptance rate. Nullable.
composite_score	Number	No	Composite score. Nullable.
deadline_regular	String	No	Regular deadline date. Format: date. Nullable.
event_start_date	String	No	Event start date. Format: date. Nullable.
deadline_extended	String	No	Extended deadline date. Format: date. Nullable.
notification_date	String	No	Notification date. Format: date. Nullable.
submission_platforms	String Array	No	Submission platforms.
programming_directors	String Array	No	Programming directors.

Path parameters

Name

Type

Description

idREQUIRED

integer

—

▣ ENDPOINT 05 / 06

GET

Get top scored film festivals

http://localhost:8080/ryanvinson/film-festivals-around-world/top/scored/festivals

QUICKSTARTGUIDE

Quickstart

List results with the default pagination.

curl -X GET "http://localhost:8080/ryanvinson/film-festivals-around-world/top/scored/festivals?page=1&per_page=20" \
  -H "apy-token: $APY_TOKEN"

What you'll get back

Returns a JSON object with page, count, per_page, total_pages, and results fields. results is an array of objects; each item includes id, name, country, categories, and genres, plus the other fields defined in the schema when present.

{
  "page": 1,
  "count": 1,
  "per_page": 20,
  "total_pages": 1,
  "results": [
    {
      "id": 123,
      "name": "Open Photography Awards",
      "country": "United States",
      "categories": ["Photography"],
      "genres": ["Portrait"]
    }
  ]
}

TRY ITLIVE · 1 ATOM

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Returns a paginated list of top scored festivals. The response is a JSON object containing pagination metadata and a results array of festival objects.

Query Parameter(s)

Attribute	Type	Mandatory	Description
page	Integer	No	Page number to return. Default: `1`.
per_page	Integer	No	Number of results per page. Default: `20`; maximum: `100`.

Response

Returns a JSON object with page, count, results, per_page, and total_pages fields. results is an array of festival objects; each festival object includes the required fields id, name, country, categories, and genres, along with the other fields defined in the schema.

Parameter	Type	Mandatory	Description
page	Integer	Yes	Current page number.
count	Integer	Yes	Number of results returned on the current page.
results	Object Array	Yes	Array of festival objects. Each item includes:<br>- `id` (Integer, required): festival identifier<br>- `city` (String): city<br>- `name` (String, required): festival name<br>- `year` (Integer): year; nullable<br>- `state` (String): state<br>- `genres` (String Array, required): list of genres<br>- `country` (String, required): country<br>- `website` (String): website URL; format: URI<br>- `categories` (String Array, required): list of categories<br>- `event_dates` (String): event dates<br>- `regular_fee` (Number): regular fee; nullable<br>- `deadline_late` (String): late deadline; format: date; nullable<br>- `composite_score` (Number): composite score; nullable<br>- `deadline_regular` (String): regular deadline; format: date; nullable<br>- `event_start_date` (String): event start date; format: date; nullable<br>- `submission_platforms` (String Array): list of submission platforms
per_page	Integer	Yes	Number of results per page.
total_pages	Integer	Yes	Total number of pages available.

Query parameters

Name

Type

Description

pageOPTIONAL

integer

—

DEFAULT 1

per_pageOPTIONAL

integer

—

DEFAULT 20

▣ ENDPOINT 06 / 06

GET

Get film festival roster

http://localhost:8080/ryanvinson/film-festivals-around-world/festivals/:id/roster

QUICKSTARTGUIDE

Quickstart

Fetch a festival’s film list by its id, with the default page settings.

curl -X GET "http://localhost:8080/ryanvinson/film-festivals-around-world/festivals/:id/roster?page=1&per_page=20" \
  -H "apy-token: $APY_TOKEN"

What you'll get back

Returns a JSON object with festival_id, festival_name, count, page, per_page, total_pages, and results fields. results is an array of objects; each item can include id, film_year, film_award, film_genre, film_title, festival_id, film_category, and film_director.

{
  "festival_id": 123,
  "festival_name": "Toronto International Film Festival",
  "count": 2,
  "page": 1,
  "per_page": 20,
  "total_pages": 1,
  "results": [
    {
      "id": 1,
      "film_year": 2024,
      "film_award": "Best Feature",
      "film_genre": "Drama",
      "film_title": "Northern Lights",
      "festival_id": 123,
      "film_category": "Feature",
      "film_director": "Ava Martin"
    }
  ]
}

TRY ITLIVE · 1 ATOM

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Returns a paginated roster of films for the festival identified by id. The response is a JSON object with festival metadata, pagination fields, and a results array of film records.

Path Parameter(s)

Attribute	Type	Mandatory	Description
id	Integer	Yes	Festival identifier.

Query Parameter(s)

Attribute	Type	Mandatory	Description
page	Integer	No	Page number to return. Default: `1`.
per_page	Integer	No	Number of items per page. Default: `20`. Maximum: `100`.

Response

Returns a JSON object with festival_id, festival_name, count, page, per_page, total_pages, and results fields. results is an array of film objects; each item contains id, film_year, film_award, film_genre, film_title, festival_id, film_category, and film_director.

Parameter	Type	Mandatory	Description
festival_id	Integer	Yes	Festival identifier.
festival_name	String	Yes	Festival name.
count	Integer	Yes	Number of items in the current response.
page	Integer	Yes	Current page number.
per_page	Integer	Yes	Page size used for the response.
total_pages	Integer	Yes	Total number of pages available.
results	Object Array	Yes	Array of film records. Each item includes:<br>- `id` (Integer)<br>- `film_year` (Integer, nullable)<br>- `film_award` (String)<br>- `film_genre` (String)<br>- `film_title` (String)<br>- `festival_id` (Integer)<br>- `film_category` (String)<br>- `film_director` (String)

Path parameters

Name

Type

Description

idREQUIRED

integer

—

Query parameters

Name

Type

Description

pageOPTIONAL

integer

—

DEFAULT 1

per_pageOPTIONAL

integer

—

DEFAULT 20

▣ COMMON ERRORS

Errors any endpoint can return

400bad_request

Required parameter missing or malformed body.

401unauthorized

API key missing, revoked, or not authorized for this service.

429rate_limited

Your plan's per-second rate exceeded. Retry with exponential backoff.

503upstream_busy

Backend temporarily unavailable. Try again in a few seconds.