Location API v2

V2 of the Location API updates the serilization used in v1 and adds the ability to create and update locations, one at a time or in bulk.

Data format

Individual locations are presented with the same serialization format in each endpoint

Sample JSON Output

{
    "domain": "dimagi-test",
    "last_modified": "2024-03-11T19:29:16.845849",
    "latitude": "31.4100000000",
    "location_data": {
        "pop": "1001"
    },
    "location_id": "68e65fbc2dc840ff8bf03849e57aca88",
    "location_type_code": "county",
    "location_type_name": "County",
    "longitude": null,
    "name": "Fairfax County",
    "parent_location_id": "41b0bdfbae20428e9435ae8c3dcd22e7",
    "site_code": "fairfax_county"
}

List Locations

Base URL

GET https://www.commcarehq.org/a/[domain]/api/location/v2/

Locations can be filtered by the following attributes as request parameters:

Input Parameters (v2)

Name	Description	Example
`format`	Data format returned, defaults to xml	`?format=json
`site_code`	Site code for the location	`?site_code=boston`
`name`	The location’s name (case sensitive)	`?name=Boston`
`location_type_code`	The location’s type code	`?location_type_code=city`
`parent_location_id`	The UUID of the location’s direct parent	`?parent_location_id=5ce87caa-a739-4a61-a0cb-559f84a9b4b7`
`last_modified.gte`	Locations last modified on or after a specific date or datetime	`?last_modified.gte=2024-01-01`
`last_modified.gt`	Locations last modified after a specific date or datetime	`?last_modified.gt=2024-01-01`
`last_modified.lt`	Locations last modified before a specific date or datetime	`?last_modified.lt=2024-01-01`
`last_modified.lte`	Locations last modified on or before a specific date or datetime	`?last_modified.lte=2024-01-01`

The API can also be ordered by last_modified from oldest to newest with the parameter order_by=last_modified, or from newest to oldest with order_by=-last_modified. This can be used in conjunction with the last_modified.gte parameter to only fetch locations modified since your last data pull.

Sample JSON output

{
  "meta": {
    "limit": 20,
    "next": null,
    "offset": 0,
    "previous": null,
    "total_count": 2
  },
  "objects": ["<array of location objects>"]
}

Location Details

Base URL

GET https://www.commcarehq.org/a/[domain]/api/location/v2/[location_id]

Create Location (Individual)

Description

Create an individual location.

Base URL

POST https://www.commcarehq.org/a/[domain]/api/location/v2/

Required Fields

name
location_type_code

Other Fields (Optional)

Field	Description
`site_code`	The system will generate one if not provided. Must be unique on the domain.
`latitude`	Latitude coordinate of the location.
`longitude`	Longitude coordinate of the location.
`location_data`	JSON dictionary instead of a string.
`parent_location_id`	The ID will be validated to ensure the parent exists, supports child locations, and has no duplicate names.

Example Request Body

{
    "latitude": "31.41",
    "location_data": {
        "pop": "1000"
    },
    "location_type_code": "city",
    "longitude": null,
    "name": "Greenville",
    "parent_location_id": "46329a9e1bad47158739d56f6f667165"
}

Update Location (Individual)

Description

Allows editing an individual location.

Base URL

PUT https://www.commcarehq.org/a/[domain]/api/location/v2/[location_id]

Editable Fields

Field	Description
`name`	Must be unique among siblings.
`site_code`	Must be unique on the domain.
`latitude`	Latitude coordinate of the location.
`longitude`	Longitude coordinate of the location.
`location_data`	Dictionary format.
`location_type_code`	If the location has a parent, the new location type must be a valid child type of that parent.
`parent_location_id`	The parent must exist, be able to have child locations of this type, and must not already have a child with the same name.

If a part of the location’s update fails due to invalid fields, the update will not occur at all. If you wanted to update the location type and parent for the location, an example request body would be -

Example Request Body

{
    "location_type_code": "county",
    "parent_location_id": "46329a9e1bad47158739d56f6f667165"
}

Create and Update Locations (in Bulk)

Description

You may also create and update locations in bulk. Even though the method is PATCH, you can also create locations as well as update using this method.

Base URL

PATCH https://www.commcarehq.org/a/[domain]/api/location/v2/

The request body should be a list of locations, with each location as a JSON dictionary (if you are using JSON). The list should be called objects. Include location_id in the dictionary if you want to update a location, and don’t include it if you want to create a location.

When creating a location via this method, the API uses the same validation as the create endpoint. For updating, it uses the same validation as the update endpoint. For updating a location, see the table of allowed fields in the documentation for “Update”. For creating, see the table of fields under “Create Location”.

Example Request Body

{
    "objects": [
        {
            "name": "Newtown",
            "latitude": "31.41",
            "location_data": {
                "pop": "1001"
            },
            "location_type_code": "city",
            "longitude": null,
            "parent_location_id": "46329a9e1bad47158739d56f6f667165"
        },
        {
            "location_id": "eea759ae08044807be749f665a1fd39a",
            "name": "Springfield",
            "latitude": "32.42",
            "location_data": {
                "pop": "1004"
            }
        }
    ]
}

With this request body, the first dictionary will create a location called “Newtown”, and update a location with the ID eea759ae08044807be749f665a1fd39a to have the name “Springfield”.

Lastly, the PATCH request is atomic. Meaning if validation fails for a single location in the request, none of the locations will be created or updated.