Pigs public API - technical overview

Created by Sean Schoeman, Modified on Mon, 2 Dec, 2024 at 1:30 PM by Marina Gherghe

Authentication
Usage
API endpoints

Authentication

A JWT access token is required to retrieve data from the Pigs public API. This can be retrieved using the /v1/Authentication/GetAccessToken endpoint. The endpoint will return the access token in the below format.

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtp...",
  "token_type": "Bearer",
  "expires_in": "3600"
}

This access token should be added to each API call in the "Authorization" header as seen below in the curl call:

curl -X GET "https://public-api-pigvision.agrovision.com/v1/Farms/GetFarms" -H "accept: text/plain" -H "Authorization: Bearer eyJhbGciOiJS..."

Usage

All requests require a farmIdentifier to be provided. This can be found using the /v1/Farms endpoint.
/v1/Farms will return some identifiable information on the farm (farm name, CPH number (official farm number)) the unique farmIdentifier and the date the farm was last updated.

Each record returned by the API endpoints has an ExternalId that can be used to identify the individual records. These ExternalIds are unique across the entire API.

There are 2 ways to retrieve data from the Pigs public API.

For performance reasons, please retrieve data back to maximum 1 year in the past.

Using the date range endpoints

These endpoints are ideal for retrieving the data of a new farm or in the case when a full reload is required.

The “startDate” and “endDate” parameters on these endpoints refer to events whose date is between the start and end date provided to the request.

In the case of endpoints which retrieve animals (e.g. IndividualAnimal/GetAnimals), the birthdate of the animal will be used when providing “startDate” and “endDate” to the request.

Because these dates are not necessarily sequential, these endpoints are not suitable for retrieving changes to the data. Please use the Changes or AllChanges endpoint for retrieving changes, depending on your use case.

Using the changes endpoints

Changes/Changes endpoint

This endpoint should be used only for farms for which data has already been retrieved through the date range endpoints. All request parameters of this endpoint are mandatory at the time of writing.

Request parameters

farmIdentifier – the identifier of the farm changes should be retrieved for
fromChangeDateTime
1. it refers to the date when data got imported into AgroVision’s data exchange program
2. it does not refer to the date of animal events or birthdates
3. it should be at a time after all the relevant date range endpoints got called
4. it should be according to UTC
page
1. starts from 1
2. should be incremented by 1 for each subsequent request, until the response contains an empty list
limit
1. how many records to retrieve at once
2. at the moment of writing, a maximum of 1000 records can be retrieved at once through this endpoint

Request example

The request url should look like this: https://public-api-pigvision.agrovision.com/v1/Changes/Changes?farmIdentifier=A8909AB2-34DB-4D77-A56B-B6F211678507&fromChangeDateTime=2024-10-14%2000%3A00%3A00&page=1&limit=1000

If the response contains items, then call the endpoint again, this time with “page=2”. Then with “page=3” and so on.

What is included in the response:

a list of animals and animal events which have been inserted, updated, or deleted from the data exchange system after fromChangeDateTime
if an animal or event has been updated, only its last change will be returned
at the moment of writing, the items in the response are ordered according to the order they got inserted into the system

What is not included in the response:

animals and animal events which have been both inserted and deleted in the period after fromChangeDateTime
records that have been imported exactly on fromChangeDateTime, or before it
“data” object for records with action “Delete”
“data” object for records with actions “Insert” or "Update" followed by “Delete”

When an empty list is returned in the response, there are no more changes to retrieve until the next import into the data exchange system. Depending on farmers’ activity and data exchange settings, changes may come in daily, once a week, or at larger intervals.

An explanation of the purpose of each property is described below:

[
  {
    //A json serialized string of the latest state of the data record.
    "data": "string",

    //Relates directly to the data found in the date range endpoints.
    //E.g. data retrieved from the /v1/Reproduction/GetWeanings endpoint, will have a 
    //dataType of "Weaning" in the /v1/changes endpoint.
    "dataType": "Weaning",

    //The system date of the change when it was added to the database.
    "changeDateTime": "2024-05-27",

    //The type of change that occurred, specifically "Insert", "Update" or "Delete".
    "action": "Insert",

    //The unique identifiable ID of the record that has changed. 
    //This will be the same as the ExternalId in the serialized json and the same as the
    //ExternalId returned from the related records date range endpoint.
    "externalId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
]

Changes/AllChanges endpoint

This endpoint should be used only in the case where the results from Changes/Changes are not clear (e.g. to check why a sow’s service is missing). It should not be called often, because it has a higher impact on other processes compared to Changes/Changes, and we would like to ensure everyone is getting as good performance as they can.

This endpoint is, at the time of writing, available only between 17:00-22:00 UTC.

Request parameters

farmIdentifier - the identifier of the farm changes should be retrieved for
fromChangeDateTime
1. it refers to the date when data got imported into AgroVision’s data exchange program
2. it does not refer to the date of animal events or birthdates
3. it should be at a time after the other endpoints got called
4. it should be used only for the first request (when nextStartingPoint is unknown)
5. it should be according to UTC
nextStartingPoint
1. it is first known when it is returned by the first request made with fromChangeDateTime filled in
2. should be used on the next request
3. each subsequent request will return a new one to be used next
limit
1. how many records to retrieve at once
2. at the moment of writing, a maximum of 1000 records can be retrieved at once through this endpoint

What is included in the response:

the full list of animals and animal events which have been inserted, updated, or deleted from the data exchange system after fromChangeDateTime
at the moment of writing, the items in the response are ordered according to the order they got inserted into the system
nextStartingPoint which should be used for the next request, if there are changes

What is not included in the response:

records that have been imported exactly on fromChangeDateTime, or before it
“data” object for records with action “Delete”
“data” object for records with action “Insert” followed by “Delete”

Example of the expected flow with the AllChanges endpoint

The first request should be done with fromChangeDateTime, but without nextStartingPoint:

The request url should look like this: https://public-api-pigvision.agrovision.com/v1/Changes/AllChanges?farmIdentifier=A8909AB2-34DB-4D77-A56B-B6F211678507&fromChangeDateTime=2023-10-14%2000%3A00%3A00.0000000&limit=1000

It returns a value with name “nextStartingPoint” in the response:

If the first response is not empty, the next request uses the value of nextStartingPoint from the first response:

The request url should look like this: https://public-api-pigvision.agrovision.com/v1/Changes/AllChanges?farmIdentifier=A8909AB2-34DB-4D77-A56B-B6F211678507&nextStartingPoint=M1s1XZOZSCkVhoyTrhToNw%3D%3D&limit=1000

If the response is not empty, the next request uses nextStartingPoint from the previous request:

The request url should look like this: https://public-api-pigvision.agrovision.com/v1/Changes/AllChanges?farmIdentifier=A8909AB2-34DB-4D77-A56B-B6F211678507&nextStartingPoint=myaZI+vkiBD+/Y1Jy2beQg%3D%3D&limit=1000

The process should be repeated until status 204 (No content) is returned. That means there are no (more) changes to retrieve.

API endpoints

For information about specific endpoints, please visit the swagger documentation:
https://public-api-pigvision.agrovision.com/swagger/index.html