-
Notifications
You must be signed in to change notification settings - Fork 0
Home
The Forge Replication API is built on GraphQL, a modern API framework.
After obtaining your Authorization Token you can explore the Replication API easily with common tools that support GraphQL queries such as Postman, Insomnia or GraphiQL.
The Forge Replication API also returns Listing and Agent results in RESO Data Dictionary format.
You'll need to send your API token in an authorization header with each request:
Authorization: Bearer %TOKEN%
Here's a query to get a look at every MLS you have access to.
query GetMLSList {
mlses {
key
name
address
state
}
}Example Response:
{
"data": {
"mlses": [
{
"key": "armls",
"name": "Arizona MLS",
"address": null,
"state": [
"Arizona"
]
},
{
"key": "rmls",
"name": "Regional MLS",
"address": null,
"state": [
"Oregon",
"Washington"
]
}
]
}
}Here's an example Request / Response for replicating listings:
GraphQL Query:
query ReplicateListings(
$mls_key: String!
$latest_event:Int!
$filter: [DataDictionaryFilterType]
) {
mls(key: $mls_key) {
listings(
last_event_id: $latest_event
filter: $filter
) {
latest_event
remaining
results {
DELETED
ListingId
ListingKey
UnparsedAddress
StandardStatus
PostalCode
ListDate
CloseDate
BedroomsTotal
BathroomsTotalInteger
Photos
ForgeFeatures { name value }
}
}
}
}GraphQL Arguments:
{
"mls_key": "armls",
"latest_event": 0
}To start, we're sending "latest_event": 0 because we don't have any data yet.
Now let's look at the response:
{
"data": {
"mls": {
"listings": {
"latest_event": 194729,
"remaining": 6464,
"results": [
//...
]
}
}
}
}Before we look at the results array, let's first look at latest_event and remaining.
Every response will return a latest_event which you will need to save to send as the latest_event argument in the next request. I would suggest it only be set after you have successfully handled the results that have been returned in the request.
The purpose of remaining is to signal how many events there are left to process. In this sample response we have 6464 events remaining. This should signal to your consumer to immediately send another request, with the new latest_event value. When you receive "remaining": 0 that should signal to your consumer that you are current with the dataset and can wait to send the next request for updates. I would suggest waiting at least 1 minute.
Obviously the main point of replication is to get at the results array. There's a few things worth noting here. The fields available are RESO Data Dictionary fields, with a couple exceptions.
DELETED
Since the Forge Replication API is event based, records that have been removed from the system will have corresponding events. In this case DELETED will be true and all other fields will be null except for the ListingKey ( or MemberKey for replicating agent records). It's worth noting that DELETED will be true for records you no long have access to also. Either way, this should trigger your consumer to remove this record from your dataset.
ForgeFeatures
One of the major benefits of the Forge Replication API is uniformity of the data. However, in order to make the data truly uniform and predicable, we have created a field that contains arbitrary listing information. This data is formatted with the intention of being displayed only, and not analyzed. The data in ForgeFeatures is NOT guaranteed to be RESO Data Dictionary compliant.
Photos
Forge will always provide an array of urls for Photos.
Results Array
The main thing to note here is that the results array is set to return 500 records. This is not configurable. Our aim is to provide the fastest, most robust experience possible. This allows the server to anticipate what's going to been needed next to provide a higher level of service.
Example Listing Result:
{
"DELETED": null,
"ListingId": "140345",
"ListingKey": "1102414",
"UnparsedAddress": "LOT 43 BOBCAT CIRCLE",
"City": "Red Lodge",
"StateOrProvince": "MT",
"PostalCode": "59068",
"ListDate": "2004-02-04T00:00:00",
"StandardStatus": "Withdrawn",
"ListPrice": 27500,
"CloseDate": null,
"BedroomsTotal": null,
"BathroomsTotalInteger": null,
"Remarks": "Terrific view of the mountains.",
"Latitude": 45.162238,
"Longitude": -109.260524,
"ForgeFeatures": [
{
"name": "Disclosure",
"value": "Not on File"
},
{
"name": "Electric",
"value": "Available"
},
{
"name": "Gas",
"value": "Available"
},
{
"name": "Lot Description",
"value": "Golf Course, Level"
},
{
"name": "Lot Num",
"value": "43"
},
{
"name": "Numberof Lots",
"value": "1"
},
{
"name": "Restrictions",
"value": "See Deed"
},
{
"name": "Road Frontage",
"value": "75"
},
{
"name": "Sewer",
"value": "In Street, Stubbed In"
},
{
"name": "Topography",
"value": "Level"
},
{
"name": "Water",
"value": "In Street, Stubbed In"
},
{
"name": "Zone",
"value": "Residential 9600"
}
]
}