We’re continuously adding new features to our API to make it easier for developers to integrate with our data and share great local businesses through their apps. Today, we’re releasing access to query our data via GraphQL, a graph query language. This is available immediately through our developer beta program.

What is GraphQL?

GraphQL is a query language for APIs that places emphasis on being able to query for exactly the data you want. I’m sure most of you at some point have thought, “I really wish this endpoint had more data,” or, “I only need one or two pieces of data from this huge API response,” or, “I wish I could make one API call instead of 2 or 3 to get the data I want.” GraphQL gives you the flexibility to control exactly what data you get back from our API! For example, if you want some data, the query could be:

{
  business(id: "garaje-san-francisco") {
    name
    url
    photos
  }
}

And we’ll return to you

{
  "data": {
    "business": {
      "name": "Garaje",
      "url": "https://yelp.com/biz/garaje-san-francisco",
      "photos": [
        "https://s3-media2.fl.yelpcdn.com/bphoto/_nN_DhLXkfwEkwPNxne9hw/o.jpg"
      ]
    }
  }
}

If you want more data about a business, then just add those attributes to your query:

{
  business(id: "garaje-san-francisco") {
    name
    url
    photos
    rating
    review_count
    categories {
      title
    }
  }
}

Which will give you

{
  "data": {
    "business": {
      "name": "Garaje",
      "url": "https://yelp.com/biz/garaje-san-francisco",
      "photos": [
        "https://s3-media2.fl.yelpcdn.com/bphoto/_nN_DhLXkfwEkwPNxne9hw/o.jpg"
      ],
      "rating": 4.5,
      "review_count": 1132,
      "categories": [
        {
          "title": "Mexican"
        },
        ...  // trimmed for the blog post
      ]
    }
  }
}

As the name implies, GraphQL also makes traversing graphs (and therefore relational data) very easy. Unlike most REST APIs, you don’t need to make multiple requests to pull relational data. Based on the schema, you can retrieve data based on the relations they have. For our API users, this means easy access to all the great business information we have available:

{
  business(id: "garaje-san-francisco") {
    reviews {
      user {
        name
      }
    }
  }
}

This sample query would let you pull the name of users who’ve written reviews on a business, something that normally takes multiple calls on a REST API.

This is only scratching the surface. Read our intro to GraphQL and our usage guide to dive more into what you could do with GraphQL and our data. We’ve setup GraphiQL, an in-browser IDE for GraphQL, and have put many examples throughout all of the docs.

What’s this about a beta program?

Today we’re also rolling out a developer beta program for our API. Right now the only component to it will be GraphQL, but we’ll be adding new content and features over the next few months and we want to give our developers the ability to try them out early and give us feedback. You can sign up now through the manage app page.

Back to blog