🗺️Getting Started

About this API 📍

CurbIQ's Curb API is a REST API to access curb rules in regions covered by CurbIQ. Curb 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.

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	If the API provided information about a specific zone, the identifier might be a path parameter like this: GET https://yzij4d8qel.execute-api.ca-central-1.amazonaws.com/v1/curbs/zones/{curb_zone_id} In this example, {curb_zone_id} would be replaced by the specific zone identifier to access its curb data.	In the CurbIQ API, authentication is done via a query parameter called curbiq_token. An example request with a query parameter would look like this: GET https://yzij4d8qel.execute-api.ca-central-1.amazonaws.com/v1/curbs?curbiq_token=your_token_here Here, curbiq_token is the query parameter that authenticates the request.

2. 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://yzij4d8qel.execute-api.ca-central-1.amazonaws.com/v1/

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

3. 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://yzij4d8qel.execute-api.ca-central-1.amazonaws.com/v1/curbs?curbiq_token=your_token_here

Replace your_token_here with the actual token provided to you.

4. 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:

GET https://yzij4d8qel.execute-api.ca-central-1.amazonaws.com/v1/curbs?curbiq_token=your_token_here

Explanation:

• GET: The HTTP method to fetch data.

• https://yzij4d8qel.execute-api.ca-central-1.amazonaws.com/v1/curbs: The endpoint to get curb rules.

• &curbiq_token=your_token_here: The authentication token passed as a query parameter.

5. 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:

{
  "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"
              ]
            }
          ]
        }
      ]
    }
  ]
}

6. 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:

import requests

# Set your token 
curbiq_token = 'your_token_here'

# API URL
url = f'https://yzij4d8qel.execute-api.ca-central-1.amazonaws.com/v1/curbs?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