# API Calls

### **Application Programming Interface (API)**

It's a "contract" that defines how separate software interacts with each other.

### **HTTP Requests**

**GET -** get data (what are the available timings tomorrow)

**POST -** creating or inserting new data (making a lunch reservation)

**PUT** - update existing data (updating the timing for a lunch reservation)

**DELETE** - deletes data (removing your lunch reservation)

### Let's Start

First, we import an external library that helps us make API calls

```python
import requests
```

Next, we will query an API of your choice.

* Google the API you are looking for (e.g. searching "random cat facts API" )
* We will then make use of this API: <https://catfact.ninja/>

<figure><img src="/files/aSp1pioFafYtMaSlXy3D" alt=""><figcaption><p>The Cat Facts API</p></figcaption></figure>

To obtain a random fact, we call `.get` on `/fact`

```python
# add /fact to the end of the API url
endpoint = "https://catfact.ninja/fact"


# Sends a GET request to the endpoint
# This calls a random fact 
response = requests.get(endpoint)
response
```

* When running this, you should get `<Response [200]>` .
* A status code of 200 means the API call was successful.

Let's call the data we received

```python
response.text
```

We should get a random fact about cats in a dictionary

<pre class="language-python" data-overflow="wrap"><code class="lang-python"><strong># '{"fact":"Some common houseplants poisonous to cats include: English Ivy, iris, mistletoe, philodendron, and yew.","length":103}'
</strong></code></pre>

API responses are typically encoded as JSON (JavaScript Object Notation). For us to use it in python, we can call the `.json()` method to convert it into a dictionary.

```python
response.json()
```

{% code overflow="wrap" %}

```python
# {"fact":"Some common houseplants poisonous to cats include: English Ivy, iris, mistletoe, philodendron, and yew.","length":103}

# type: dict
```

{% endcode %}

Call the fact and print the String

```
fact = response.json()["fact"]
print(fact)
```

{% code overflow="wrap" %}

```python
# Some common houseplants poisonous to cats include: English Ivy, iris, mistletoe, philodendron, and yew.
```

{% endcode %}

### **Piecing it all together**

```python
def get_cat_fact():
    endpoint = "https://catfact.ninja/fact"
    response = requests.get(endpoint)
    fact = response.json()["fact"]
    return fact

print(get_cat_fact())
```

### Another Example

Finding the parking lots available at a carpark

Description of the API can be found [here](https://beta.data.gov.sg/datasets/d_ca933a644e55d34fe21f28b8052fac63/view)

```python
endpoint = "https://api.data.gov.sg/v1/transport/carpark-availability"

response = requests.get(endpoint)
```

&#x20;This sends a query to the API to obtain the carpark availability

```python
# Need to figure out how to navigate the data to extract only what is necessary

carpark_data = response.json()["items"][0]["carpark_data"]
len(carpark_data)
```

Retreives the number number of carparks with data

```python
for carpark_info in all_carpark_info:
    if carpark_info["carpark_number"] == "HE12":
        print(carpark_info)
        break
# pulls out the respective information of capark HE12
```


---

# 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://wiki.nushackers.org/orbital/telegram-bot/api-calls.md?ask=<question>
```

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.