Larks API specification
Larks api offers you the ability to integrate your apps with larks API. You can query demographic locations such as Country, Provinces, Municipalities and Suburbs.
Address
Create Country division with an object
Create locations division based on geocoding. With this method you can provide a name of a registration webhook
POST /api/Address/CreateCountryDemographicDivision
Request
{
"osmtype": "way",
"osm_id": 60334883,
"lat": "-8.83794705",
"lon": "13.234773948986573",
"displayname": "Hotel Forum, Travessa Ho Chi Mimh, Martires de Kifangondo, Distrito Urbano da Maianga, Luanda, Município de Luanda, Luanda, Angola",
"address": {
"tourism": "Hotel Forum",
"road": "Travessa Ho Chi Mimh",
"suburb": "Martires de Kifangondo",
"city": "Luanda",
"county": "Município de Luanda",
"state": "Luanda",
"ISO31662lvl4": "AO-LUA",
"country": "Angola",
"countrycode": "ao"
}
}
Create Country division by geoloaction with webhook
Create a country division based on a particular object. You need to provide an object with a registered hookname and an optional responseId, and optionalId.
The optional id is to be included with an enpoint. Example https://www.site.com/route?optionalparameter=optionalId
POST /api/Address/CreateDivisionsByGeolocation
{
"optionalId": "",
"hookname": "",
"responseId": "",
"lat": "",
"lng": ""
}
Create Country division by geoloaction
Create a country division based on a particular geolocation.
POST /api/Address/CreateLocationByGeoposition
{
"lat":
"lng":
}
Category
Get All Categories
Returns all location categories, in a particular language. parameter has to be a language code en,pt,fr
GET /api/category?lang={parameter}
Response
[
{
"id": 6,
"designation": "Mercado",
"lng": "pt"
},
{
"id": 9,
"designation": "Governo",
"lng": "pt"
}
]
Create category
Create a new category to be associated with a location.
POST /api/category
Request
{
"designation":"Parks",
"lng":"en"
}
Update a category
Create a new category to be associated with a location.
PATCH /api/category?categoryId=parameter
Request
{
"id": 1,
"designation": "Parks",
"lng": "en"
}
City
Create City
Create a new city based on a object
POST /api/City
Request
{
"provinceId": "2",
"designation": "Kilamba"
}
Get city by Id
Get a city based on the Id of that city. The parameter is the id of the city currently registered in larks.
GET /api/city/city?cityId=parameter
Response
{
"provinceId": 2,
"id": 14,
"designation": "TestCity"
}
Get cities in a province
Returns all the cities in a province. The parameter is the province id.
GET /api/City/citiesinprovince?provinceId=parameter
Response
[
{
"provinceId": 2,
"id": 2,
"designation": "Pretoria"
},
{
"provinceId": 2,
"id": 3,
"designation": "Midrand"
},
{
"provinceId": 2,
"id": 4,
"designation": "Randburg"
},
{
"provinceId": 2,
"id": 5,
"designation": "Roodepoort"
}
]
Get country cities
Returns all the cities in a spefic country. The parameter is the country id.
GET /api/City/citiesincountry?countryId=parameter
Response
[
{
"provinceId": 3,
"id": 11,
"designation": "Cacuaco"
},
{
"provinceId": 3,
"id": 18,
"designation": "Luanda"
},
{
"provinceId": 6,
"id": 15,
"designation": "M'banza Congo"
},
{
"provinceId": 7,
"id": 16,
"designation": "Lobito"
},
{
"provinceId": 8,
"id": 17,
"designation": "Lubango"
}
]
Country
Get All Countries
Retrieve all countries in stored in LARKS
GET /api/countries/allcountries
[
{
"id": 123,
"designation": "Angola"
},
{
"id": 564,
"designation": "République démocratique du Congo"
},
{
"id": 452,
"designation": "South Africa"
}
]
Get country by country Id
Retrieves a single country by Id and it includes provinces and municipalities or districts or cities.
GET /api/countries?id=parameter
{
"id": 123,
"designation": "République démocratique du Congo",
"provinces": [
{
"id": 1,
"designation": "Kinshasa",
"countryId": 1231,
"districts": [
{
"id": 12231,
"designation": "Gombe",
"provinceId": 11
}
],
"cities": [
{
"provinceId": 11,
"id": 112312,
"designation": "Kinshasa"
}
]
}
]
}
Get Country by given name
Retrieves a country and its provinces or states by the country given name.
GET /api/countries/countryByName?countryName=Country name
{
"id": 2,
"designation": "South Africa",
"provinces": [
{
"id": 2,
"designation": "Gauteng",
"countryId": 2
},
{
"id": 4,
"designation": "Western Cape",
"countryId": 2
},
{
"id": 5,
"designation": "Eastern Cape",
"countryId": 2
}
]
}
Districts
Create District
Create a new district based on a object, under a specific province
POST /api/district
Request
{
"designation": "Barumbu",
"provinceId": "1"
}
Get District
Returns a single district, based on a district id.
GET /api/district?districtId=parameter
Request
{
"id": 2,
"designation": "Barumbu",
"provinceId": 1
}
Get districts in a particular province.
Returns a list of districts that belong to a single province.
GET /api/district/districtsinprovice?provinceId=parameter
Request
[
{
"id": 1,
"designation": "Gombe",
"provinceId": 1
},
{
"id": 2,
"designation": "Barumbu",
"provinceId": 1
}
]
Location
Create Location
GET /api/location/CategoryLocations?categoryid=
GET /api/location/locationbydistance?distance=
GET /api/location/locationbydistanceandcategory?distance=
GET /api/location/locationsincity?cityId=
GET /api/location/locationsinmunicipality?municipalityId=
Create a new location with images and a specific division. This end point expects a form-data, this is because you can create locations with images or videos
POST /api/newLocation
Request
curl --location 'https://larks.africa/api/Location/newLocation' \
--form 'designation="Mercedez Midrand"' \
--form 'additionalInfo="Mercedez benz main seller in Midrand. "' \
--form 'countryId="1"' \
--form 'municipalityID="1"' \
--form 'categoryId="1"' \
--form 'suburbId="3"' \
--form 'subCategories="4"' \
--form 'subCategories="3"' \
--form 'Files=' \
--form 'cityId="3"' \
--form 'lat="-25.973972"' \
--form 'Lng="28.117133"'
Response
{
"id": 12,
"designation": "BMW Waterfall",
"country": null,
"countryId": 2,
"listofCountryDTO": null,
"municipalityID": 1,
"suburbId": 5,
"cityId": 3,
"subCategories": [
4,
3
],
"files": null,
"additionalInfo": "BMW sellerlocated in front of mall of africa.",
"categoryId": 1,
"lat": -26.011366,
"lng": 28.109463
}
Get locations by Category
Retrieve list of locations with images and a specific divisions. This end point expects a form-data, this is because you can create locations with images or videos
GET /api/location/CategoryLocations?categoryid=parameter
Response
[
{
"id": 9,
"designation": "A corner in Lever",
"additionalInformation": "A random place opposite Sandridge.",
"categoryId": 2,
"category": "Industry",
"subcategory": [
{
"id": 2,
"designation": "Supermarket",
"categoryId": 8
},
{
"id": 3,
"designation": "Assembleia",
"categoryId": 9
}
],
"images": [
"7f663084-d289-4ae4-9778-1d4de5817a57.PNG"
],
"lat": -25.97628,
"lng": 28.119166
}
]
Location by distance
Retrieve a list of locations with images and divisions. This end point expects a geoposition and a distance in KM.
GET /api/location/locationbydistance?distance=1.0&pageNumber=1&pageSize=2&lat=-25.973419&lng=28.119508
Response
{
"pageNumber": 3,
"pageSize": 2,
"firstPage": "https://localhost:44339/api/location/locationbydistance?distance=1&lat=-25.973419&lng=28.119508&pageNumber=1&pageSize=2",
"lastPage": "https://localhost:44339/api/location/locationbydistance?distance=1&lat=-25.973419&lng=28.119508&pageNumber=3&pageSize=2",
"totalPages": 3,
"totalRecords": 6,
"nextPage": null,
"previousPage": "https://localhost:44339/api/location/locationbydistance?distance=1&lat=-25.973419&lng=28.119508&pageNumber=2&pageSize=2",
"data": [
{
"id": 10,
"designation": "Mercedez Midrand",
"additionalInformation": "Mercedez benz main seller in Midrand. ",
"category": "Industry",
"categoryId": 2,
"municipality": "City of Johannesburg Metropolitan Municipality",
"suburb": "Carlswald",
"city": "Midrand",
"distance": 0.52755942626975,
"lat": -25.978129,
"lng": 28.118871,
"subcategories": [
{
"id": 2,
"designation": "Supermarket",
"categoryId": 0,
"lng": "en"
},
{
"id": 3,
"designation": "Assembleia",
"categoryId": 0,
"lng": "pt"
}
],
"images": [
"05473a99-acc5-497e-ae70-615164690e12.jpg"
]
},
{
"id": 11,
"designation": "Mercedez Midrand",
"additionalInformation": "Mercedez benz main seller in Midrand. ",
"category": "Business",
"categoryId": 1,
"municipality": "City of Johannesburg Metropolitan Municipality",
"suburb": "Carlswald",
"city": "Midrand",
"distance": 0.245235899549542,
"lat": -25.973972,
"lng": 28.117133,
"subcategories": [
{
"id": 3,
"designation": "Assembleia",
"categoryId": 0,
"lng": "pt"
},
{
"id": 4,
"designation": "Offices",
"categoryId": 0,
"lng": "en"
}
],
"images": [
"20eefc2a-558b-4155-981a-531fb1c0d7c4.jpg"
]
}
],
"succeeded": true,
"errors": null,
"message": null
}
Location by distance and category
Retrieve a list of locations with images and divisions. This end point expects a form-data, this is because you can create locations with images or videos
GET /api/location/locationbydistanceandcategory?distance=1.0&category=2&pageNumber=1&pageSize=2&lat=-25.973419&lng=28.119508
Response
{
"pageNumber": 1,
"pageSize": 2,
"firstPage": "https://localhost:44339/api/location/locationbydistanceandcategory?distance=1&category=2&lat=-25.973419&lng=28.119508&pageNumber=1&pageSize=2",
"lastPage": "https://localhost:44339/api/location/locationbydistanceandcategory?distance=1&category=2&lat=-25.973419&lng=28.119508&pageNumber=3&pageSize=2",
"totalPages": 3,
"totalRecords": 5,
"nextPage": "https://localhost:44339/api/location/locationbydistanceandcategory?distance=1&category=2&lat=-25.973419&lng=28.119508&pageNumber=2&pageSize=2",
"previousPage": null,
"data": [
{
"id": 3,
"designation": "Carlswald",
"additionalInformation": "Some place close to Sandridge in carlswald",
"category": "Industry",
"categoryId": 2,
"municipality": "City of Johannesburg Metropolitan Municipality",
"suburb": "Carlswald",
"city": "Midrand",
"distance": 0.695597950283581,
"lat": -25.978936,
"lng": 28.116227,
"subcategories": [
{
"id": 2,
"designation": "Supermarket",
"categoryId": 0,
"lng": "en"
},
{
"id": 3,
"designation": "Assembleia",
"categoryId": 0,
"lng": "pt"
}
],
"images": [
"Speed test1.PNG"
]
},
{
"id": 4,
"designation": "A fine Circle",
"additionalInformation": "Some place close to carlswald",
"category": "Industry",
"categoryId": 2,
"municipality": "City of Johannesburg Metropolitan Municipality",
"suburb": "Carlswald",
"city": "Midrand",
"distance": 0.885508634450344,
"lat": -25.978446,
"lng": 28.112637,
"subcategories": [
{
"id": 2,
"designation": "Supermarket",
"categoryId": 0,
"lng": "en"
},
{
"id": 3,
"designation": "Assembleia",
"categoryId": 0,
"lng": "pt"
}
],
"images": [
"Speed test1.PNG"
]
}
],
"succeeded": true,
"errors": null,
"message": null
}
Locations in a particular city
Retrieve a list of locations with images and divisions. This end point returns a list of locations in a particular city.
GET /api/location/locationsincity?cityId={parameter}&pageNumber=1&pageSize=2
Response
{
"pageNumber": 2,
"pageSize": 3,
"firstPage": "https://localhost:44339/api/location/locationsinmunicipality?municipalityId=1&pageNumber=1&pageSize=3",
"lastPage": "https://localhost:44339/api/location/locationsinmunicipality?municipalityId=1&pageNumber=2&pageSize=3",
"totalPages": 2,
"totalRecords": 6,
"nextPage": null,
"previousPage": "https://localhost:44339/api/location/locationsinmunicipality?municipalityId=1&pageNumber=1&pageSize=3",
"data": [
{
"id": 9,
"designation": "A corner in Lever",
"additionalInformation": "A random place opposite Sandridge.",
"category": "Industry",
"categoryId": 2,
"municipality": "City of Johannesburg Metropolitan Municipality",
"suburb": "Carlswald",
"city": "Midrand",
"distance": 0,
"lat": -25.97628,
"lng": 28.119166,
"subcategories": [
{
"id": 2,
"designation": "Supermarket",
"categoryId": 0,
"lng": "en"
},
{
"id": 3,
"designation": "Assembleia",
"categoryId": 0,
"lng": "pt"
}
],
"images": [
"7f663084-d289-4ae4-9778-1d4de5817a57.PNG"
]
},
{
"id": 10,
"designation": "Mercedez Midrand",
"additionalInformation": "Mercedez benz main seller in Midrand. ",
"category": "Industry",
"categoryId": 2,
"municipality": "City of Johannesburg Metropolitan Municipality",
"suburb": "Carlswald",
"city": "Midrand",
"distance": 0,
"lat": -25.978129,
"lng": 28.118871,
"subcategories": [
{
"id": 2,
"designation": "Supermarket",
"categoryId": 0,
"lng": "en"
},
{
"id": 3,
"designation": "Assembleia",
"categoryId": 0,
"lng": "pt"
}
],
"images": [
"05473a99-acc5-497e-ae70-615164690e12.jpg"
]
},
{
"id": 11,
"designation": "Mercedez Midrand",
"additionalInformation": "Mercedez benz main seller in Midrand. ",
"category": "Business",
"categoryId": 1,
"municipality": "City of Johannesburg Metropolitan Municipality",
"suburb": "Carlswald",
"city": "Midrand",
"distance": 0,
"lat": -25.973972,
"lng": 28.117133,
"subcategories": [
{
"id": 3,
"designation": "Assembleia",
"categoryId": 0,
"lng": "pt"
},
{
"id": 4,
"designation": "Offices",
"categoryId": 0,
"lng": "en"
}
],
"images": [
"20eefc2a-558b-4155-981a-531fb1c0d7c4.jpg"
]
}
],
"succeeded": true,
"errors": null,
"message": null
}
Locations in a particular municipality
Retrieve a list of locations with images and divisions. This end point returns a list of locations in a particular municipality.
GET /api/location/locationsinmunicipality?municipalityId={parameter}&pageNumber=1&pageSize=2
Response
{
"pageNumber": 1,
"pageSize": 4,
"firstPage": "https://localhost:44339/api/location/locationsincity?cityId=3&pageNumber=1&pageSize=4",
"lastPage": "https://localhost:44339/api/location/locationsincity?cityId=3&pageNumber=2&pageSize=4",
"totalPages": 2,
"totalRecords": 6,
"nextPage": "https://localhost:44339/api/location/locationsincity?cityId=3&pageNumber=2&pageSize=4",
"previousPage": null,
"data": [
{
"id": 3,
"designation": "Carlswald",
"additionalInformation": "Some place close to Sandridge in carlswald",
"category": "Industry",
"categoryId": 2,
"municipality": "City of Johannesburg Metropolitan Municipality",
"suburb": "Carlswald",
"city": "Midrand",
"distance": 0,
"lat": -25.978936,
"lng": 28.116227,
"subcategories": [
{
"id": 2,
"designation": "Supermarket",
"categoryId": 0,
"lng": "en"
},
{
"id": 3,
"designation": "Assembleia",
"categoryId": 0,
"lng": "pt"
}
],
"images": [
"Speed test1.PNG"
]
},
{
"id": 4,
"designation": "A fine Circle",
"additionalInformation": "Some place close to carlswald",
"category": "Industry",
"categoryId": 2,
"municipality": "City of Johannesburg Metropolitan Municipality",
"suburb": "Carlswald",
"city": "Midrand",
"distance": 0,
"lat": -25.978446,
"lng": 28.112637,
"subcategories": [
{
"id": 2,
"designation": "Supermarket",
"categoryId": 0,
"lng": "en"
},
{
"id": 3,
"designation": "Assembleia",
"categoryId": 0,
"lng": "pt"
}
],
"images": [
"Speed test1.PNG"
]
},
{
"id": 8,
"designation": "Midauto",
"additionalInformation": "A place where you can fix your car and at the same time get drinks with your friends. ",
"category": "Industry",
"categoryId": 2,
"municipality": "City of Johannesburg Metropolitan Municipality",
"suburb": "Carlswald",
"city": "Midrand",
"distance": 0,
"lat": -25.977531,
"lng": 28.115977,
"subcategories": [
{
"id": 2,
"designation": "Supermarket",
"categoryId": 0,
"lng": "en"
},
{
"id": 3,
"designation": "Assembleia",
"categoryId": 0,
"lng": "pt"
}
],
"images": [
"957b8764-bc2e-4380-a9f5-d52bbeaadc15.PNG"
]
},
{
"id": 9,
"designation": "A corner in Lever",
"additionalInformation": "A random place opposite Sandridge.",
"category": "Industry",
"categoryId": 2,
"municipality": "City of Johannesburg Metropolitan Municipality",
"suburb": "Carlswald",
"city": "Midrand",
"distance": 0,
"lat": -25.97628,
"lng": 28.119166,
"subcategories": [
{
"id": 2,
"designation": "Supermarket",
"categoryId": 0,
"lng": "en"
},
{
"id": 3,
"designation": "Assembleia",
"categoryId": 0,
"lng": "pt"
}
],
"images": [
"7f663084-d289-4ae4-9778-1d4de5817a57.PNG"
]
}
],
"succeeded": true,
"errors": null,
"message": null
}
Media
Get Location Media
Return an image of if it exists in the larks filestore.
GET/api/media/locationimages?category=category&filename=filename
Response
image/jpeg
Municipalities
Create a new municipality.
Creates a new municipality under a specific province.
POST /api/Municipality
Request
{
"designation": "Município de Luanda",
"provinceid": "1"
}
Get Municipality
Returns a single municipality object.
GET/api/Municipality?muncipalityId=parameter
Response
{
"id": 3,
"designation": "City of Ekurhuleni Metropolitan Municipality",
"provinceId": 2,
"points": null,
"isUpdateCoordinates": false
}
Get municipalities .
Returns a list of municipalities in a specific province.
GET /api/Municipality/MunicipalitiesInProvince?provinceId=parameter
Response
[
{
"id": 4,
"designation": "Município do Cacuaco",
"provinceId": 3,
"points": null,
"isUpdateCoordinates": false
},
{
"id": 13,
"designation": "Município do Belas",
"provinceId": 3,
"points": null,
"isUpdateCoordinates": false
},
{
"id": 14,
"designation": "Município de Luanda",
"provinceId": 3,
"points": null,
"isUpdateCoordinates": false
}
]
Provinces
Create Province
Creates a new procince based on a specific object.
POST/api/Province
Response
{
"countryId": "2",
"designation": "Province Name"
}
Provinces in a country
Returns a list of provinces based on a particular country by name.
GET/api/province/ProvincesInCountry?countryname=parameter
Response
[
{
"id": 3,
"designation": "Luanda",
"countryId": 3
},
{
"id": 6,
"designation": "Zaire",
"countryId": 3
},
{
"id": 7,
"designation": "Benguela",
"countryId": 3
},
{
"id": 8,
"designation": "Huíla",
"countryId": 3
}
]
Provinces in a country
Returns a list of provinces based on a country id.
GET/api/province/CountryProvinces?CountryId=parameter
Response
[
{
"id": 3,
"designation": "Luanda",
"countryId": 3,
"municipalities": [
{
"id": 4,
"designation": "Município do Cacuaco",
"provinceId": 3
},
{
"id": 13,
"designation": "Município do Belas",
"provinceId": 3
},
{
"id": 14,
"designation": "Município de Luanda",
"provinceId": 3
}
],
"cities": [
{
"provinceId": 3,
"id": 11,
"designation": "Cacuaco"
},
{
"provinceId": 3,
"id": 18,
"designation": "Luanda"
}
]
},
{
"id": 6,
"designation": "Zaire",
"countryId": 3,
"cities": [
{
"provinceId": 6,
"id": 15,
"designation": "M'banza Congo"
}
]
},
{
"id": 7,
"designation": "Benguela",
"countryId": 3,
"municipalities": [
{
"id": 12,
"designation": "Catumbela",
"provinceId": 7
}
],
"cities": [
{
"provinceId": 7,
"id": 16,
"designation": "Lobito"
}
]
},
{
"id": 8,
"designation": "Huíla",
"countryId": 3,
"cities": [
{
"provinceId": 8,
"id": 17,
"designation": "Lubango"
}
]
}
]
Subcategories
Create a new subcategories.
Creates a new subcategories under a specific category.
POST/api/Subcategory
Request
{
"designation": "Offices",
"categoryId": "1",
"lng": "en"
}
Get subcategories by id.
Returns an object of a subcategory. Parameter represents subcategory id.
GET /api/Subcategory/SubcategoriesInCategory?categoryId=parameters
Response
[
{
"id": 1,
"designation": "Manufacturers",
"categoryId": 21,
"lng": "en"
},
{
"id": 1,
"designation": "Industry",
"categoryId": 34,
"lng": "en"
}
]
Get subcategories under a specific category.
Returns a list of subcategories under a specific category. Parameter represents category id.
GET /api/subcategory/Subcategory?id=parameters
Response
{
"id": 3,
"designation": "Assembleia",
"categoryId": 9,
"lng": "pt"
}
Get all subcategories.
Returns a list of all the subcategories, under a specific language. The supported languages codes are en,pt,fr
GET /api/Subcategory/Allsubcategories?lang=paramenter
Response
[
{
"id": 1,
"designation": "Manufacturers",
"categoryId": 2,
"lng": "en"
},
{
"id": 2,
"designation": "Supermarket",
"categoryId": 8,
"lng": "en"
},
{
"id": 4,
"designation": "Offices",
"categoryId": 1,
"lng": "en"
}
]
Suburbs
Get suburbs by sector
Returns a list of all suburbs that under a specific sector, this sector can be district, municipality or city. The id parameter represents the id of provided sector
GET/api/suburb/sectorNeighbourhood?sector=municipality&id=
Response
[
{
"id": 2,
"municipalityId": 1,
"designation": "Carlswald"
},
{
"id": 4,
"municipalityId": 1,
"designation": "Barbeque Downs"
},
{
"id": 7,
"municipalityId": 1,
"designation": "Wilgeheuwel"
},
{
"id": 13,
"municipalityId": 1,
"designation": "Benmore Gardens"
},
{
"id": 14,
"municipalityId": 1,
"designation": "Wendywood"
},
{
"id": 15,
"municipalityId": 1,
"designation": "Rivonia Gardens"
},
{
"id": 16,
"municipalityId": 1,
"designation": "Johannesburg Ward 93"
},
{
"id": 17,
"municipalityId": 1,
"designation": "Witkoppen Extensions"
}
]
Get a single suburb
Returns an object of a single suburb.
GET/api/suburb/Suburb?id=parameter
Response
{
"id": 18,
"municipalityId": 4,
"designation": "Cacuaco"
}
Get a list of suburbs
Returns a list of suburbs based on the given list of id
GET/api/suburb/ListOfSuburb?suburbsQuery=2,3
Response
[
{
"id": 2,
"designation": "Carlswald"
},
{
"id": 3,
"designation": "Hatfield"
}
]
Get a list of suburbs by query parameter
Returns a list of suburbs based on the given list of id
GET/api/suburb/SuburbList?suburbList=2&suburbList=3
Response
[
{
"id": 2,
"designation": "Carlswald"
},
{
"id": 3,
"designation": "Hatfield"
}
]