Example: Displaying Standard Field Labels

Standard fields have MLS-defined labels fit for display on listing reports. Additionally, some listing fields have values from a pre-determined list. For these fields, human readable values must be retrieved from the corresponding meta data service.

1. Authentication
2. Retrieving standard fields for the MLS
3. Retrieving listing data
4. Retrieving list item values for the City field

Step 1: Authentication

This example expects that you have already obtained an OAuth 2 authorization token to access a user's data. Read more on our OpendID Connect Authentication and OAuth 2 Authorization.

Step 2: Retrieving standard fields for the MLS

First, you'll need to consult the Listing Meta: Standard Fields service. Standard fields meta data rarely changes, so we recommend you cache this response locally.

In the example below, we find that the MLS label for BedsTotal is "Total Bedrooms"; thus, you should display this string on human-readable reports when presenting bedrooms information.

Lastly, we also see that the City field has HasList set to true. We know, then, that we'll need to make another API request label (Step 4) to find the appropriate label for each city.

The below response is intentionally abridged.

$ curl "https://sparkapi.com/v1/standardfields" -H "Authorization: OAuth MY_OAUTH2_ACCESS_TOKEN"  

{
    "D": {
        "Success": true,
        "LastUpdated":"2012-11-01T20:55:02Z",
        "Results": [
            {
                "BedsTotal": {
                    "Label": "Total Bedrooms",
                    "Searchable": true,
                    "Type": "Integer",
                    "ResourceUri": "/v1/standardfields/BedsTotal",
                    "MlsVisible": {
                        "PropertyTypes": ["A","B","C"]
                    }
                },
                "City": {
                    "Label": "City",
                    "Searchable": true,
                    "Type": "Character",
                    "ResourceUri": "/v1/standardfields/City",
                    "HasList": true,
                    "MlsVisible": {
                        "PropertyTypes": ["A","B","C"]
                    }
                }
            }
        ]
    }
}

Step 3: Retrieving listing data

As in the previous example, the below response is intentionally abridged.

$ curl "https://sparkapi.com/v1/listings/20100000000000000000000000" -H "Authorization: OAuth MY_OAUTH2_ACCESS_TOKEN"  
{
    "D": {
        "Success": true,
        "Results": [
            {
                "ResourceUri": "/vX/listings/20100000000000000000000000",
                "Id": "20100000000000000000000000",
                "StandardFields": {
                  "City": "FAR",
                  "BedsTotal": 8
                }
            }
        ]
    }
}

Step 4: Retrieving list item values for the City field

Finally, since HasList was set to true in Step 2 for the City field, we'll need to find the appropriate label for the value 'FAR'. In the response below, we find that listing reports should display 'Fargo' to the end user.

$ curl "https://sparkapi.com/v1/standardfields/City" -H "Authorization: OAuth MY_OAUTH2_ACCESS_TOKEN"  
{
    "D": {
        "Success": true,
        "Results": [
            {
                "PropertySubType": {
                    "Label": "City",
                    "Searchable": true,
                    "Type": "Character",
                    "ResourceUri": "/v1/standardfields/City",
                    "MlsVisible": {
                        "PropertyTypes": ["A","B","C"]
                    },
                    "HasList": true,
                    "FieldList": [
                        {
                            "Value": "FAR",
                            "Name": "Fargo",
                            "AppliesTo": [
                                "A",
                                "B",
                                "C"
                            ]
                        },
                        {
                            "Value": "MOOR",
                            "Name": "Moorhead",
                            "AppliesTo": [
                                "A",
                                "B",
                                "C"
                            ]
                        }
                    ]
                }
            }
        ]
    }
}