# Getting Started

### About this API 📍

CurbIQ's Curbs API is a REST API to access curb rules in regions covered by CurbIQ.\
Curbs API provides all output data as a JSON in modified CurbIQ CDS (CCDS) format - that is, CDS plus a little extra on the side 😉

### 1. Understanding the Basics of REST APIs

* A **REST API** allows you to interact with a web service by sending HTTP requests (like GET, POST) and receiving data in response, usually in a format like JSON (JavaScript Object Notation).
* The CurbIQ API is a **RESTful service** that lets you retrieve information about curb rules, which are specific regulations or restrictions governing how curbsides in certain areas can be used.

### 2. Query Parameters vs Path Parameters

In the CurbIQ API, both query parameters and path parameters are used to specify details about the request, but they serve different purposes and are used in different ways.

|                | **Path Parameters**                                                                                                                                                                                                                                                                                                       | **Query Parameters**                                                                                                                                                                                                                                                                                                                                    |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Definition** | Path parameters are variables in the URL path that indicate the specific resource you're requesting. They are part of the endpoint and define which resource or resources are being accessed.                                                                                                                             | Query parameters are key-value pairs that are added to the URL after a \`?\` symbol. They are used to filter, sort, or refine the data returned by the API.                                                                                                                                                                                             |
| **Usage**      | Path parameters are typically used when identifying a specific resource or collection within the API. They are embedded directly in the URL structure.                                                                                                                                                                    | Query parameters allow for greater flexibility in specifying the details of a request, such as adding filters, searching for specific data, or providing authentication tokens.                                                                                                                                                                         |
| **Example**    | <p>If the API provided information about a specific zone, the identifier might be a path parameter like this:<br><code>GET https://v2.curbiq-curb-api.io/curbs/zones/{curb_zone_id}</code><br>In this example, <code>{curb_zone_id}</code> would be replaced by the specific zone identifier to access its curb data.</p> | <p>In the CurbIQ API, authentication is done via a query parameter called <code>curbiq_token</code>. An example request with a query parameter would look like this:<br><code>GET https://v2.curbiq-curb-api.io/curbs?curbiq_token=your_token_here</code><br>Here, <code>curbiq_token</code> is the query parameter that authenticates the request.</p> |

### 3. CDS vs. CCDS vs. Custom Attributes

When working with CurbIQ, it’s important to understand the distinction between **CDS**, **CCDS**, and **Custom** parameters and responses, as they define the flexibility and scope of the system’s functionality:

#### 1. **CDS (Curb Data Specification)**

CDS parameters and responses strictly adhere to the standards defined by the **Open Mobility Foundation (OMF)**. These are foundational, standardized data elements designed to ensure compatibility across jurisdictions and systems. CurbIQ directly implements these parameters and responses as specified in the OMF documentation, ensuring compliance with global best practices.

#### 2. **CCDS (CurbIQ Curb Data Specification)**

CCDS expands upon the standard CDS by introducing additional parameters and responses developed by **CurbIQ**. These are tailored to enhance functionality and address specific needs that go beyond the scope of the CDS. CCDS serves as an optional extension, offering more granular or advanced capabilities while maintaining alignment with the core principles of CDS.

#### 3. **Custom**

Custom parameters and responses are fully configurable elements requested by individual cities. These are developed to meet unique requirements or address specific use cases that are not covered by CDS or CCDS. This level of customization allows cities to tailor the system to their exact needs, ensuring maximum relevance and utility for their specific curb management goals.

### 4. Base URL

The **base URL** for the CurbIQ API is the root address where you will send your requests:

The CurbIQ API base URL is:\
`https://v2.curbiq-curb-api.io/`

This means that to access any specific resource (like a city's curb rules), you will append additional paths or parameters to this URL.

### 5. Authentication

*   **Authentication** is done via a **token** that you pass as a query parameter called `curbiq_token`. This token authenticates you as a valid user of the API.

    ```
    Example:
    https://v2.curbiq-curb-api.io/curbs/zones?curbiq_token=your_token_here
    ```

Replace `your_token_here` with the actual token provided to you.

### 6. Making a Request

* **HTTP Methods**: The API uses standard HTTP methods like `GET` to retrieve data.
* **GET** requests are the most common and are used to fetch data from the API.

**Example Request**:

```bash
GET https://v2.curbiq-curb-api.io/curbs/zones?curbiq_token=your_token_here
```

Explanation:

* GET: The HTTP method to fetch data.
* https://v2.curbiq-curb-api.io/curbs/zones: The endpoint to get curb zones.
* \&curbiq\_token=your\_token\_here: The authentication token passed as a query parameter.

### 7. Handling the Response

* When you make a successful request, the API will return data in JSON format.
* JSON is a lightweight format used for structuring data, and it looks something like this:

```json
{
  "type": "curbiq_api_response",
  "request_type": "search_by_zone",
  "request_parameters": {
    "curb_zone_id": "1"
  },
  "responses": [
    {
      "curb_zone_id": "1",
      "policies": [
        {
          "rules": [
            {
              "activity": "no stopping",
              "user_classes": [
                "curb cut"
              ]
            }
          ]
        }
      ]
    }
  ]
}
```

### 8. Error Handling

* If there’s an issue with your request (e.g., invalid token, wrong parameters), the API will return an error response. You need to handle these errors in your code by checking the HTTP status code:
  * **200**: Success.
  * **400**: Error in the request

### Example Code (Python)

Here's a basic example of how you might interact with the CurbIQ API using Python:

```python
import requests

# Set your token 
curbiq_token = 'your_token_here'

# API URL
url = f'https://v2.curbiq-curb-api.io/curbs/zones?curbiq_token={curbiq_token}'

# Make a GET request to the API
response = requests.get(url)

# Check if the request was successful
if response.status_code == 200:
    # Parse the JSON response
    data = response.json()
    print(data)
else:
    print(f"Error: {response.status_code} - {response.text}")
```

All request types are specified in the API Reference section.

✨ You can try it now on your own by visiting the following URL in your browser:\
[Demo](https://api.curbiq.io/demo/v1/dublin/demo?)
