Example: Searching Listings

When searching listings, familiarity with the Standard Fields service as well as the Search and Paging Syntax is vital.

1. Authentication
2. Retrieve standard field data for City
3. Searching listings by City
4. Paginating our results

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: Retrieve standard field data for City

First, we'll pull down the meta data for the City Standard Field. We see from the meta data below that it is Searchable and will be unmasked (e.g. MlsVisible) for the property types "A", "B", "C", "D", and "E". Since HasList is true, all possible listing values fall into a defined set of strings advertised in FieldList.

$ curl "https://sparkapi.com/v1/standardfields/City" -H "Authorization: OAuth MY_OAUTH2_ACCESS_TOKEN"  
{
    "D": {
        "Success": true,
        "Results": [
         "City": {
            "ResourceUri": "/v1/standardfields/City",
            "HasList": true,
            "MaxListSize": 4,
            "Searchable": true,
            "MlsVisible": [
              "A",
              "B",
              "C",
              "D",
              "E"
            ],
            "Type": "Character",
            "FieldList": [
              {
                "Name": "Great Falls",
                "Value": "GREAT FALLS"
              },
              {
                "Name": "Augusta",
                "Value": "AUGUSTA"
              },
              {
                "Name": "Babb",
                "Value": "BABB"
              },
              {
                "Name": "Belgrade",
                "Applies To": [
                  "A",
                  "B",
                  "C",
                  "D"
                ],
                "Value": "BELGRADE"
              }
            ]
          }
        ]
    }
}

Step 3: Searching listings by City

Since "Augusta", unlike "Belgrade", is present in all property types, we'll use that City to search on in our example. Note that we want to use the Value, "AUGUSTA". The Value attribute is intended for use while searching, while the Name attribute is intended for display to the end user.

We'll include three parameters from the Search and Paging Syntax page: _filter for searching, _pagination to return pagination information, and _limit to only select a single listing at a time.

We'll also include the _select Attribute Selection parameter to limit the standard fields that are returned.

$ curl "https://sparkapi.com/v1/listings?_filter=City+Eq+%27AUGUSTA%27&_pagination=1&_limit=1&_select=City" -H "Authorization: OAuth MY_OAUTH2_ACCESS_TOKEN"  
{
    "D": {
        "Success": true,
        "Results": [
          {
            "Id": "20100000000000000000000000",
            "ResourceUri": "/v1/listings/20100000000000000000000000",
            "StandardFields": {
              "City": "AUGUSTA"
            }
          }
        ],
        "Pagination": {
          "TotalRows": 100,
          "PageSize": 1,
          "CurrentPage": 1,
          "TotalPages": 100
        }
    }
}

Step 4: Searching listings by City

Viewing the next set of results is as simple as adding the _page parameter, and setting it to the next page: 2.

$ curl "https://sparkapi.com/v1/listings?_filter=City+Eq+%27AUGUSTA%27&_pagination=1&_limit=1&_select=City&_page=2" -H "Authorization: OAuth MY_OAUTH2_ACCESS_TOKEN"  
{
    "D": {
        "Success": true,
        "Results": [
          {
            "Id": "20100000000000000000000001",
            "ResourceUri": "/v1/listings/20100000000000000000000001",
            "StandardFields": {
              "City": "AUGUSTA"
            }
          }
        ],
        "Pagination": {
          "TotalRows": 100,
          "PageSize": 1,
          "CurrentPage": 2,
          "TotalPages": 100
        }
    }
}