▣ 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

https://api.eu.apyhub.com/ryanvinson/film-festivals-around-world/festival/countries

QUICKSTART

GUIDE

Quickstart

This GET request fetches the festival count summary.

curl -X GET "https://api.eu.apyhub.com/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	Description
count	Integer	Total number of items returned in `results`.
results	Object Array	Array of country objects. Each item contains: - `country`: string - `festival_count`: integer

▣ ENDPOINT 02 / 06

GET

List categories

https://api.eu.apyhub.com/ryanvinson/film-festivals-around-world/categories

QUICKSTART

GUIDE

Quickstart

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

curl -X GET "https://api.eu.apyhub.com/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	Description
count	Integer	Total count returned by the endpoint.
results	Object Array	Array of category objects. Each item contains: - `count` (`Integer`): Count associated with the category. - `category` (`String`): Category name.

▣ ENDPOINT 03 / 06

GET

List film festivals

https://api.eu.apyhub.com/ryanvinson/film-festivals-around-world/festivals/list

QUICKSTART

GUIDE

Quickstart

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

curl -X GET "https://api.eu.apyhub.com/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	Description
q	String	Search query string.
page	Integer	Page number. Default: `1`.
sort	ENUM	Sort order. Allowed values: `name`, `deadline`, `event_date`.
genre	String	Filter by genre.
state	String	Filter by state.
country	String	Filter by country.
fee_max	Number	Maximum fee value.
category	String	Filter by category.
per_page	Integer	Number of results per page. Default: `20`. Maximum: `100`.
deadline_after	String	Filter by deadlines on or after this date. Format: `date`.
deadline_before	String	Filter by deadlines on or before this date. Format: `date`.
event_date_before	String	Filter by event dates on or before this date. Format: `date`.
submission_platform	String	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	Description
page	Integer	Current page number.
count	Integer	Number of results returned in the response.
per_page	Integer	Results per page.
total_pages	Integer	Total number of pages available.
results	Object Array	Array of festival objects. Each item includes `id`, `name`, `country`, `categories`, and `genres` as required fields.

▣ ENDPOINT 04 / 06

GET

Get film festival detail

https://api.eu.apyhub.com/ryanvinson/film-festivals-around-world/festival/detail/:id

QUICKSTART

GUIDE

Quickstart

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

curl -X GET "https://api.eu.apyhub.com/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	Description
id	Integer	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	Description
id	Integer	Festival identifier.
city	String	City associated with the festival.
fees	Object	Fee information. Nullable.
name	String	Festival name.
year	Integer	Festival year. Nullable.
state	String	State associated with the festival.
genres	String Array	Genre labels for the festival.
country	String	Festival country.
website	String	Festival website URL. Format: URI.
categories	String Array	Festival categories.
description	String	Festival description.
event_dates	String	Event dates as a string.
past_winners	Object Array	Past winners. Nullable; item shape is not defined in the schema.
year_founded	Integer	Year the festival was founded. Nullable.
deadline_late	String	Late deadline date. Format: date. Nullable.
accepts_awards	Boolean	Whether the festival accepts awards.
event_end_date	String	Event end date. Format: date. Nullable.
acceptance_rate	Number	Acceptance rate. Nullable.
composite_score	Number	Composite score. Nullable.
deadline_regular	String	Regular deadline date. Format: date. Nullable.
event_start_date	String	Event start date. Format: date. Nullable.
deadline_extended	String	Extended deadline date. Format: date. Nullable.
notification_date	String	Notification date. Format: date. Nullable.
submission_platforms	String Array	Submission platforms.
programming_directors	String Array	Programming directors.

▣ ENDPOINT 05 / 06

GET

Get top scored film festivals

https://api.eu.apyhub.com/ryanvinson/film-festivals-around-world/top/scored/festivals

QUICKSTART

GUIDE

Quickstart

List results with the default pagination.

curl -X GET "https://api.eu.apyhub.com/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	Description
page	Integer	Page number to return. Default: `1`.
per_page	Integer	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	Description
page	Integer	Current page number.
count	Integer	Number of results returned on the current page.
results	Object Array	Array of festival objects. Each item includes: - `id` (Integer, required): festival identifier - `city` (String): city - `name` (String, required): festival name - `year` (Integer): year; nullable - `state` (String): state - `genres` (String Array, required): list of genres - `country` (String, required): country - `website` (String): website URL; format: URI - `categories` (String Array, required): list of categories - `event_dates` (String): event dates - `regular_fee` (Number): regular fee; nullable - `deadline_late` (String): late deadline; format: date; nullable - `composite_score` (Number): composite score; nullable - `deadline_regular` (String): regular deadline; format: date; nullable - `event_start_date` (String): event start date; format: date; nullable - `submission_platforms` (String Array): list of submission platforms
per_page	Integer	Number of results per page.
total_pages	Integer	Total number of pages available.

▣ ENDPOINT 06 / 06

GET

Get film festival roster

https://api.eu.apyhub.com/ryanvinson/film-festivals-around-world/festivals/:id/roster

QUICKSTART

GUIDE

Quickstart

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

curl -X GET "https://api.eu.apyhub.com/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	Description
id	Integer	Festival identifier.

Query Parameter(s)

Attribute	Type	Description
page	Integer	Page number to return. Default: `1`.
per_page	Integer	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	Description
festival_id	Integer	Festival identifier.
festival_name	String	Festival name.
count	Integer	Number of items in the current response.
page	Integer	Current page number.
per_page	Integer	Page size used for the response.
total_pages	Integer	Total number of pages available.
results	Object Array	Array of film records. Each item includes: - `id` (Integer) - `film_year` (Integer, nullable) - `film_award` (String) - `film_genre` (String) - `film_title` (String) - `festival_id` (Integer) - `film_category` (String) - `film_director` (String)

▣ 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.

Similar APIs

Closest matches in the catalog based on this service.

CALLCompare Beaches Around the WorldRyan Vinson CALLWorld News APISkycraft CALLPublic Holidays APIApyHub CALLGet Top Domains by Country APIDosvak LLC

From the blog

Reads that touch this API.

Enhance Travel Platforms with SharpAPI’s AI-Powered Travel APIs on ApyHubAug 5, 2026 Top 5 Free AI Resume Parsers for Recruiters in 2025Sep 10, 2026 Exploring the Top Video Thumbnail ( Preview) APIsJul 9, 2026 Timezones Dictionary API: Global Timezone Data and Best Alternatives for 2026Jul 9, 2026