Overview of GraphQL

The Parcl Labs api is built with GraphQL, a flexible query language that allows you to return as much or as little data as you need.

Unlike REST APIs where there are multiple endpoints returning different data, GraphQL always exposes one endpoint and allows you to determine the structure of the returned data.

The result of each query will be formatted in the same way as the query itself.

📘

NOTE

For a deep-dive into what you can do with GraphQL, check out the GraphQL Foundation's introduction here.

Operations

The Parcl Labs API is run off of the operation query.

Query

A query performs the READ operation and does not change or alter any data.

Below is an example of a query that retrieves the last price feed for the New York MSA:

query priceFeed {
  MSA(where: {MSA_NAME: {_eq: "New York-Newark-Jersey City, NY-NJ-PA"}}) {
    MSA_NAME
    parcl_price_feed(limit: 1, order_by: {DATE: desc}) {
      DATE
      PARCL_PRICE_FEED
    }
  }
}

Object Types

Object types are a collection of fields, which are used to describe the set of possible data you can query using the API.

Fields

Fields specify certain properties of objects.

Each object contains fields that can be queried by name to retrieve specific properties of the object.

query {
    MSA {
      MSA_NAME
    }
}

Arguments

You can pass arguments in a query to determine the returned data (i.e. filtering the search results) and to narrow down the results to only the specific ones you're after.

In the following example, the object is MSA, the requested field is MSA_NAME and PARCL_ID, the argument is MSA_NAME, and the argument value is New York-Newark-Jersey City, NY-NJ-PA

query getParclID {
  MSA(where: {MSA_NAME: {_eq: "New York-Newark-Jersey City, NY-NJ-PA"}}) {
    MSA_NAME
    PARCL_ID
  }
}