Find Person by Query

gns-api/persons

API to return the person(s) for a specific query.

Persons represent...

  • players
  • officials (if applicable)

Response Schema: https://gns-schemas.sports.gracenote.com/gns.xsd / https://gns-schemas.sports.gracenote.com/gns.json

Request Parameters

Parameter Mandatory Description Example(s) 
query Yes

Make a request based on a specific query. See examples below.


accept Yes

Choose between XML and JSON for the response..

skip No Indicate the number of results to skip in the response.
limit No Indicate the maximum number of results in the response.
fields No Allows you to return the id(s) and only specific field(s) in the response. names

Queries

Query Description Example
firstName, lastName Make a request based on the first name, last name or both for a person(s).

{"firstName": "Lonzo"}

{"lastName": "Ball"}

{"firstName": "Lonzo", "lastName": "Ball"}

city, state or country Make a request based on the city, state (if appliocable) or country for the birth place of a person(s).

{"city": "Boston"}

{"country": "Italy"}

gender
Make a request for persons based on gender.
{"gender": "MALE"}
{} Returns all persons.

Response Body

Response

Description

id

Unique Gracenote id for the person.

xids

Container for external ids to connect to data in other Gracenote APIs and/or legacy data.

supplier Name of the supplier (e.g. sportsdirect, infostrada, tms) of the xid.
type The description of the supplier's id keyspace.
id The supplier's id for the associated entity.
name The name of the person.
type The type of name for the person (e.g. FIRST, LAST).
value The value for the type of name for the person (e.g. Crosby)
birthdate The birthdate (e,g, 1987-03-31) for the person.
height_inches The height of the person in inches.
height_millimetres The height of the person in millimetres.
weight_pounds The weight of the person in pounds.
weight_grams The weight of the person in grams.
gender The gender of the person.
birth_place
city The city for the birth place of the person.
state The state for the birth place of the person, if applicable.
country The country for the birth place of the person.

Sample

Sample Request

Query: {"firstName": "Lonzo", "lastName": "Ball"}

Sample Response

 

<persons>
        <person>
            <id>GNEFSHGKYS5E8T7</id>
            <meta>
                <update_date>2018-02-28T07:24:32.847Z</update_date>
            </meta>
            <xids>
                <xid>
                    <supplier>sportsdirect</supplier>
                    <type>xml</type>
                    <id>/sport/basketball/player:774924</id>
                </xid>
                <xid>
                    <supplier>infostrada</supplier>
                    <type>general_person</type>
                    <id>1619837</id>
                </xid>
            </xids>
            <names>
                <name>
                    <type>FIRST</type>
                    <value>Lonzo</value>
                </name>
                <name>
                    <type>LAST</type>
                    <value>Ball</value>
                </name>
            </names>
            <birthdate>1997-10-27</birthdate>
            <height_inches>78</height_inches>
            <weight_pounds>190</weight_pounds>
            <height_millimetres>1981</height_millimetres>
            <weight_grams>86182</weight_grams>
            <gender>MALE</gender>
            <birth_place>
                <city>Chino Hills</city>
                <state>California</state>
                <country>USA</country>
            </birth_place>
        </person>
    </persons>

Docs Navigation