Getting Started

Connect to the Parcl Labs API and make your first request

To make your very first Parcl Labs API request, follow these steps:

Navigate to the Hasura GraphQL Explorer
Enter the following url: https://api.parcllabs.com/v1/graphql in the Enter an endpoint url... prompt, and click on Connect to Endpoint.

In the Request Headers section, enter your API key in a new field under Authorization as shown in the screen shot below. Lets say your API key is YWRhbS5idXNoasyOFAtbWBpI1NMNi96. Your Request Headers should look exactly like below:

Now that you are authenticated, it's time to take the API for a spin! Let's write a simple query to get a list of all the MSAs in the MSA table. The current iteration of the API includes MSAs from the Case-Shiller 20, minus Dallas, TX.

query MSANames {
  MSA {
    MSA_NAME
  }
}

This query should return the following JSON response:

{
  "data": {
    "MSA": [
      {
        "MSA_NAME": "Atlanta-Sandy Springs-Alpharetta, GA"
      },
      {
        "MSA_NAME": "Portland-Vancouver-Hillsboro, OR-WA"
      },
      {
        "MSA_NAME": "Charlotte-Concord-Gastonia, NC-SC"
      },
      {
        "MSA_NAME": "Minneapolis-St. Paul-Bloomington, MN-WI"
      },
      {
        "MSA_NAME": "San Francisco-Oakland-Berkeley, CA"
      },
      {
        "MSA_NAME": "Cleveland-Elyria, OH"
      },
      {
        "MSA_NAME": "Phoenix-Mesa-Chandler, AZ"
      },
      {
        "MSA_NAME": "Miami-Fort Lauderdale-Pompano Beach, FL"
      },
      {
        "MSA_NAME": "Seattle-Tacoma-Bellevue, WA"
      },
      {
        "MSA_NAME": "Denver-Aurora-Lakewood, CO"
      },
      {
        "MSA_NAME": "New York-Newark-Jersey City, NY-NJ-PA"
      },
      {
        "MSA_NAME": "Washington-Arlington-Alexandria, DC-VA-MD-WV"
      },
      {
        "MSA_NAME": "Detroit-Warren-Dearborn, MI"
      },
      {
        "MSA_NAME": "Tampa-St. Petersburg-Clearwater, FL"
      },
      {
        "MSA_NAME": "Chicago-Naperville-Elgin, IL-IN-WI"
      },
      {
        "MSA_NAME": "Los Angeles-Long Beach-Anaheim, CA"
      },
      {
        "MSA_NAME": "Las Vegas-Henderson-Paradise, NV"
      },
      {
        "MSA_NAME": "San Diego-Chula Vista-Carlsbad, CA"
      },
      {
        "MSA_NAME": "Boston-Cambridge-Newton, MA-NH"
      }
    ]
  }
}

Great! We have successfully queried the API! Now we can start building queries that return more useful data. Let's start by focusing on a specific MSA, and retrieve for it the Parcl Price Feed over the last week. We can write the following query to get this data for the New York area MSA. Note here, even for a relatively simple query, we are already using more advanced concepts, including filtering, joining tables, sorting, and limiting the data returned.

query NYMSAPriceFeed {
  MSA(where: {MSA_NAME: {_ilike: "%new york%"}}) {
    MSA_NAME
    PARCL_ID
    parcl_price_feed(limit: 7, order_by: {DATE: desc_nulls_last}) {
      DATE
      PARCL_ID
      PARCL_PRICE_FEED
    }
  }
}

This should return the following JSON:

{
  "data": {
    "MSA": [
      {
        "MSA_NAME": "New York-Newark-Jersey City, NY-NJ-PA",
        "PARCL_ID": 2900187,
        "parcl_price_feed": [
          {
            "DATE": "2023-01-17",
            "PARCL_ID": 2900187,
            "PARCL_PRICE_FEED": 336.8177560054946
          },
          {
            "DATE": "2023-01-16",
            "PARCL_ID": 2900187,
            "PARCL_PRICE_FEED": 335.8885283846155
          },
          {
            "DATE": "2023-01-14",
            "PARCL_ID": 2900187,
            "PARCL_PRICE_FEED": 335.8988331868133
          },
          {
            "DATE": "2023-01-13",
            "PARCL_ID": 2900187,
            "PARCL_PRICE_FEED": 335.66344525824184
          },
          {
            "DATE": "2023-01-12",
            "PARCL_ID": 2900187,
            "PARCL_PRICE_FEED": 335.89349959890114
          },
          {
            "DATE": "2023-01-11",
            "PARCL_ID": 2900187,
            "PARCL_PRICE_FEED": 335.9112520934067
          },
          {
            "DATE": "2023-01-10",
            "PARCL_ID": 2900187,
            "PARCL_PRICE_FEED": 335.65613824725284
          }
        ]
      }
    ]
  }
}