Hi all,
as announced earlier the Location API is no longer with us in the API v3 version. It was a beast of an API, too smart for its own good and certainly to smart for the API team!
So we created a bunch of new API's instead: Address, Email, Phone and Website. The Contact API will still get you the primary address, email and phone for a contact, and the first website. If you need more (like all the phone numbers for a contact) you can use one of the new API's. Each one has the following functions:
- create
- get
- delete
and if you use the new civicrm_api to call them you can also use 'update' as an action, and 'getfields' to get a list of all the fields on the entity.
If you try calling the Location API with version 3, you will get an error message. The existing Location API in v2 is still available.
The way to call the v3 API's is to use the new civicrm_api function with version 3 as param, for example:
$params = array('contact_id' => 1,'version' => '3');
$result = civicrm_api('Address', 'Get', $params);
At the moment the new v3 API's can be found on svn, and has been shipped with 3.4alpha1 and 2, and 4.0alpha1 and 2.
Erik
Comments
The param array can also be directly passed in the call
$result = civicrm_api('Address', 'Get', array('contact_id' => 42,'version' => '3') );
Well done erik!
On the whole, I agree that the Location API was too much complexity for not fitting any use case very well, so I think you all are going in the right direction.
There *is*, however, some need to tag addresses and phone numbers into groups like "home", "work", and other things for some applications like "voting" or "mailing". The way we used to do this was to attach the address and the phone number (and the email too, whether we liked that or not) to the location.
How does the V3 api handle this tagging-of-addresses-info use case?
I * think* you are referring to location_type_id? In the existing example it is a parameter. (I'm sure Erik will be clearer on it) NB Erik - should be also accept location_type_name?
http://svn.civicrm.org/civicrm/trunk/api/v3/examples/AddressCreate.php
Hmmm not sure about location_type_name. I think the principle where we were starting from was that we use the fields that are available in the DB table unless we have a use case for additional stuff. It would not be a problem to include location_type_name if we have a need for it? Personally I have no problem in checking for the loaction_type_id?
That is the same logic for OptionValue, knowing that activity type is group id 42 is less easy than calling with option_group_name.
The problem is documentation, that's adding yet another "hidden" field. Don't know how to solve
X+
so we get another 'hidden' thing.....but I agree it is far more user friendly. Can others voice their opinions as well?
We can document some of them by building them into the tests that generate the examples & but that is limited (in that you can't use location_type_id & location_type_name. in the same e.g).
However, I think hard coding extra fields into the getFields function would be the way to go?
Hi Rob,
the location_type_id is a param that can be used in Address, Email and Phone. So for example if I want to get the home number of contact 12 I would do a call with the params contact_id => 12 and location_type_id = 1. The downside is that you will have to check Address, Email and Phone to get the complete picture, whereas Location would give you the overview in one go ... even it did not fall over or simply not show the result in XML because there were too many levels in the result array :-)
Does that answer your question?
Erik
Hi,
Location was one of the big incentive to migrate, it was a big complex one that no one understood, and was changing from . version to . version...
Now we have something stable and simple enough that can be used without having to dig through the code (check http://civicrm.org/API_version_3 for more details)
I'm tempted for the next version(s) to make the api chainable, ala jquery. now that the basic bricks are in place...to be continued...