# Examples
These examples (and any other use of the API which passes username and password in the URL) will only work if TVheadend is configured to use 'basic' or 'basic and digest' authentication.
### curl
Parameters passed to TVH using the GET method must be URI-encoded:
`curl 'http://user:pass@localhost:9981/api/epg/events/grid?limit=999&channel=BBC%20ONE'`
Alternatively use the POST Method:
`curl --data 'limit=999&channel=BBC ONE' 'http://user:pass@localhost:9981/api/epg/events/grid'`
To make the output more human-readable, pipe it through json\_pp (included in the perl package on many distributions) or jq.
### PHP
This simple example lists some details about upcoming timers, sorted in date order. To work through a PHP-enabled web server, the PHP.INI setting "allow\_url\_fopen" must be ON.
```
TVH PHP test
| Date | Start | End | Title |
|---|
$date | $start | $stop | {$t['disp_title']} | ";
}
function get_timers() {
$url = "http://admin:admin@your.server:9981/api/dvr/entry/grid_upcoming?sort=start";
$json = file_get_contents($url);
$j = json_decode($json, true);
$ret = &$j["entries"];
return $ret;
}
?>
```
For an example of what can be done with the API in PHP see .
### Javascript
It is a 'feature' of Javascript that a script can only access remote content from the same source (IP and port number) as the script was loaded from. Hence to call the TVHeadend API from Javascript, the script must be hosted on TVHeadend's built-in web server. To do this, place your script in `/usr/share/tvheadend/src/webui/static`; it can then be accessed from URL `http://user:pass@your.server:9981/static/`. *Note that this is unintended behaviour and may change in the future.*
This example carries out the same task as the PHP example above. Your browser will prompt for the TVHeadend user and password.
```
TVH Javascript test
```
### Python
This example produces the same output as the previous ones.
```
#!/usr/bin/env python3
import json
import time
import requests
def get_timers():
ts_server = 'http://192.168.0.1:9981'
ts_url = 'api/dvr/entry/grid_upcoming?sort=start'
ts_user = 'admin'
ts_pass = 'admin'
ts_query = '%s/%s' % (
ts_server,
ts_url,
)
ts_response = requests.get(ts_query, auth=(ts_user, ts_pass))
if ts_response.status_code != 200:
print('Error code %d\n%s
' % (ts_response.status_code, ts_response.content, ))
return {}
ts_json = json.loads(ts_response.text, strict=False)
return ts_json['entries']
def main():
print('''
TVH Python test
| Date | Start | End | Title |
|---|
''')
timers = get_timers()
if len(timers):
for timer in timers:
start = time.localtime(timer['start'])
print('| %s | %s | %s | %s |
'
% (time.strftime("%a %e/%m",start),
time.strftime("%H:%M",start),
time.strftime("%H:%M",time.localtime(timer['stop'])),
timer['disp_title'],
))
print('''
''')
main()
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.tvheadend.org/documentation/development/json-api/examples.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.